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How to Use This Publication 


This publication provides a full description of the use of the OS/VS (Virtual 
Storage) utility programs. This publication assumes that the reader is familiar 
with VS terms and concepts. 


Effective use of this publication requires an understanding of the: 


Organization of the publication as a whole. 
Organization of each program description. 


Use of special referencing aids that help you find the right utility program and 
the right example. 


Required publications. 
Related publications. 


Notational conventions used to describe the syntax (or format) of utility 
control statements. 


These topics are discussed below. 


Organization of the Publication 


In addition to the preface you are now reading, a table of contents, a list of 
figures, and a list of tables, this publication has the following major parts: 


“Guide to Utility Program Functions,” which is a table arranged in 
alphabetical order of utility program functions and the programs that perform 
them. This table enables you to get to the program that can do what you need 
to have done. For additional information, see “Special Referencing Aids’’ 
below. 


“Introduction,” which introduces the utility programs and provides information 
on the differences among system, data set, and independent utility programs. 
This chapter contains basic information about how the programs are executed 
and about the utility control statements used to specify program functions. 
New or infrequent users of the utility programs should give particular attention 
to this chapter. 


20 individual chapters—one for each utility program. These chapters are in 
alphabetical order, beginning with IBCDASDI and ending with IFHSTATR. 
For a discussion of the organization of these chapters, which will help you find 
the information you need about a particular program, see “Organization of 
Program Descriptions” below. 


““Appendix A: Exit Routine Linkage,” which provides information about 
linking to and returning from optional user-supplied exit routines. This 
appendix should be read only if you plan to code or use an exit routine. If you 
are coding an exit routine, this appendix provides linkage conventions, 
descriptions of parameter lists, and return codes. If you are using an existing 
exit routine, you may be interested in the meaning of return codes from the 
exit routine. 
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¢ ‘Appendix B: Invoking Utility Programs from a Problem Program,” which 
describes the macro instructions used to invoke a utility program from a 
problem program rather than executing the utility program by job control 
statements or by a procedure in the procedure library. This appendix should 
be read only if you plan to invoke a utility program from a problem program. J 


¢« “Appendix C: DD Statements for Defining Mountable Devices,” which 
provides a review of how to define mountable volumes to ensure that no one 
else has access to them. For a definitive explanation of this subject, see 
OS/VS JCL Reference, GC28-0618. 


e ‘Appendix D: Generation Data Groups,’ which describes generation data 
groups and their indexes, and how to catalog and retrieve generation data sets. 
This appendix is included because generation data groups are not fully 
described elsewhere and because you need this background information if you 
are to manipulate generation data groups with the utility programs. This 
appendix should be read only if you intend to use utility programs to create or 
manipulate generation data sets. 


e “Appendix E: Processing User Labels,’ which describes the user-label 
processing that can be performed by IEBGENER, IEBCOMPR, IEBPTPCH, 
IEHMOVE, [EBTCRIN, and IEBUPDTE. This appendix should be read only 
if you plan to use a utility program for processing user labels. 


e “Index,’’ which is a subject index to this publication. 


Organization of Program Descriptions 


Program descriptions are all organized the same way to enable you to find 
information more easily. Each program is discussed according to the following 
pattern: 


e Introduction to and description of the functions that can be performed by the | 
program. This description typically includes an overview of the program’s use, 
definitions of terms, illustrations, etc. 


e Input and output (including return codes) used and produced by the program. 


e Control of the program through job control statements and utility control 
statements. A brief explanation of the job control statements used to execute 
the program appears in a table under “‘Job Control Statements.’ Any 
restrictions on job control statements appear under a “‘Restrictions’’ heading. 
The utility control statements are introduced in a list under “Utility Control 
Statements”’ so that you can determine which of the statements are required 
for the task to be performed. 


e Examples of using the program, including the job control statements and 
utility control statements. 


Special Referencing Aids 
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Two special referencing aids are included in this publication to help you: 
1. Locate the right utility program. 
2. Locate the right example. 


To locate the right utility program, refer to Table 1 in “‘Guide to Utility Program 
Functions,” which immediately precedes the “Introduction.” Figure 1 shows a 
portion of the table. The figure shows that you can use IEHINITT to label a 
magnetic tape volume or IEHLIST to list a volume table of contents. 


> 


Required Publications 


Related Publications 


Label magnetic tape volumes IEHINITT 


List a password entry IEHPROGM 
a volume table of contents IEHLIST 
partitioned directories [EHLIST 


Figure 1. Locating the Right Program 


To locate the right example, use the table—called an “example directory’’—that 
precedes each program’s examples. Figure 2 shows a portion of the example 
directory for IEHMOVE. The figure shows that IEHMOVE Example 1 is an 
example of moving a sequential data set and that IEHMOVE Example 2 is an 
example of copying a sequential data set. 


MOVE Sequential 3330 Disk, Source volume is demounted 
2314 Disks after job completion. 
Two mountable disks. I 
COPY Sequential 3330 Disk, Three cataloged sequential 
2314 or, data sets are to be copied. 
2319 Disks The 2314 or 2319 are 
mountable. 2 


Figure 2. Locating the Right Example 


The reader should be familiar with the following publications: 


© OS/VS Messages Library: Utilities Messages, GC38-1005, which contains a 
complete listing and explanation of the messages and codes issued by the 
utility programs and other programs. 


e OS/VS JCL Reference, GC28-0618, which contains a complete explanation 
of the job control statements available for the operating system. 


¢ OS/VS Data Management Services, GC26-3783, which describes the 
input/output facilities of the operating system. It contains information on 
record formats, data set organization, access methods, direct access device 
characteristics, data set disposition, and space allocation. 


e OS/VS Supervisor Services and Macros, GC27-6979, which contains 
information on how to use the services of the supervisor. Among the services 
of the supervisor are program management, task creation and management, 
main storage management, and checkpoint and restart. 


e OS/VS Data Management Macro Instructions, GC26-3793, which contains 
a description of the WRITE SZ, LINK, and RETURN macro instructions, and 
contains the format and contents of the DCB. 


The additional publications referred to in this publication are: 


¢ OS/VSI1 Storage Estimates, GC24-5094, and OS/VS2 Storage Estimates, 
GC28-0604, which contain storage estimates. 


© OS/VSI System Data Areas, SY28-0605, and OS/VS2 System Data 
Areas , SY28-0606, which contain a complete description of the control blocks 
used by the operating system. 


¢ IBM System/370 Principles of Operation, GA22-7000, which contains a 
description of system structure; of the arithmetic, logical, branching, status 
switching, and input/output operations; and of the interruption system. 
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Notational Conventions 


A uniform system of notation is used to describe the syntax (or format) of utility 
control statements. This notation provides a basis for describing the structure of 
utility control statements. That is, it describes which parameters are required and 


which are optional, the options available in expressing values, and the required ) 
punctuation. 
Bold Type 
In the notation, bold type (LIST, 0, etc.) is used to indicate specific values that 
can be entered. 
Italic Type 


Italic type (nn, user-information , etc.) is used where a number, character 
string, or keyword is to be inserted by the user. For instance, the italic letters in 


MODE= mm 
Tn 


must be replaced by a value when coded. 


Punctuation 


The period (.), comma (,), equal sign (=), and apostrophe (’) are used for 
punctuation and must be coded as shown. These punctuation marks serve to 
separate the parameters of a utility control statement. 


Brackets 


Brackets ([ ]) indicate that the elements and punctuation they enclose are 
optional. The brackets themselves are for descriptive purposes only, and are not 
to be coded. For instance 


value=element1 ,element2,element3[,element4] 3 


indicates that ‘“‘value=’’ must be followed by three required parameters 
(element1, element2, and element3) separated by commas. As indicated by the 
brackets, element4 is optional and need not be coded. If element4 is coded, 
however, the comma that immediately precedes it must also be coded. 


When choices are available for an optional value, the choices appear in brackets, 
one choice above another, as follows: 


value=elementO [,element] |] 
[ element? | 
[,element3 | 


In the above example, “value=” must be followed by elementO. Optionally, 
elementl, element2, or element3 can be coded. 
Braces 


Braces ({ }) indicate a required choice. The braces themselves are for descriptive 
purposes only, and are not to be coded. For example: 


value= {element] } 
felement2 } 


indicates that ‘“‘value=”’ must be followed by either element1 or element2. 
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Underscoring 


Ellipsis 


Underscoring indicates a value that is assumed by the program if no value is 
entered for that element. For example, given that no optional value is coded in 
the following: 


value= [element] ] 
[element2] 


element! is assumed. 


Ellipsis (...) is used to indicate that one or more additional parameters or sets of 
parameters, each of the same format, optionally can be added to the operand. 
For example, given the following 


value=element! ,element?... 


the ellipsis indicates that everything preceding the ellipsis and following the equal 
sign can be repeated. 
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Guide to Utility Program Functions 


Table | shows a list of tasks that the utility programs can be used to perform. The 
left-hand column shows tasks that you might want to perform. The middle column 
more specifically defines the tasks. The right-hand column shows the utility programs 
that can be used for each task. Notice that in some cases more than one program 
may be available to perform the same task. 
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Introduction 


OS/VS (Virtual Storage) provides utility programs to assist in organizing and 
maintaining data. Each utility program described in this publication falls into one 
of three classes of programs. The program class into which a utility program falls 
is determined by the function that the utility program performs and the manner 
in which the program is controlled. The program classes are: 


e System utility programs, which are used to maintain system control data at an 
organizational or system level. These programs are controlled by job control 
statements and utility control statements. 


e Data set utility programs, which are used to reorganize, change, or compare 
data at the data set and/or record level. These programs are controlled by job 
control statements and utility control statements. 


e Independent utility programs, which are used to prepare devices for system use 
when the operating system is not available. Independent utility programs 
operate outside, and in support of the operating system. These programs are 
controlled by utility control statements. 


The selection of a specific program is dependent on the nature of the job to be 
performed. For example, renaming a data set involves modifying system control 
data. Therefore, a system utility program can be used to rename the data set. In 
some cases, a specific function can be performed by more than one program. 
Table 1 in “Guide to Utility Program Functions,’ which immediately precedes 
this chapter, is provided to help you find the program that performs the function 
you need. 


L 


Control 


System and data set utility programs are controlled by job control statements and 
utility control statements. Independent utility programs are controlled by utility 
control statements; because these programs are independent of the operating 
system, job control statements are not required. The job control statements and 
utility control statements necessary to use utility programs are provided in the 
major discussion of each utility program. 


Job Control Statements 


A system or data set utility program can be introduced to the operating system in 
different ways: 


e Job control statements can be included in the input stream. 


e Job control statements, placed in a procedure library or defined as an 
in-stream procedure, can be included via the EXEC job control statement. 


¢ A utility program can be invoked by a calling program. 


If job control statements are placed in a procedure library, they should satisfy the 
requirements for most applications of the program; a procedure, of course, can 
be modified or supplemented for applications that require additional parameters, 
data sets, or devices. The data set utility IEBUPDTE can be used to enter a 
procedure into a procedure library; see “IEBUPDTE Program.” 


Independent utility programs do not require job control statements and cannot be 
( invoked by a calling program. For information on executing independent utility 
programs, see “Independent Utility Programs’’ below. 
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A job that modifies a system data set (identified by SYS1.) must be run in a 
single job environment; however, a job that uses a system data set, but does not 
modify it, can be run in a multiprogramming environment. The operator should 
be informed of all jobs that modify system data sets. 


DD statements should ensure that the volumes on which the data sets reside ) 
cannot be shared when update activity is being performed. 


Utility Control Statements 


Restrictions 
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Utility control statements are used to identify a particular function to be 
performed by a utility program and, when required, to identify specific volumes 
or data sets to be processed. 


The control statements for the utility programs have the following standard 
format: 


label operation operand 


The /abe!l symbolically identifies the control statement and, with the exception 
of system utility program IEHINITT, can be omitted. When included, a name 
must begin in the first position of the statement and must be followed by one or 
more blanks. It can contain from one to eight alphameric characters, the first of 
which must be alphabetic. 


The operation identifies the type of control statement. It must be preceded and 
followed by one or more blanks. 


The operand is made up of one or more keyword parameters separated by 
commas. The operand field must be preceded and followed by one or more 
blanks. Commas, parentheses, and blanks can be used only as delimiting 
characters. 


Comments can be written in a utility statement, but they must be separated from | 
the last parameter of the operand field by one or more blanks. } 


Utility control statements are coded on cards or as card images and are contained 
in columns 1 through 71. A statement that exceeds 71 characters must be 
continued on one or more additional cards. A non-blank character must be 
placed in column 72 to indicate continuation. A utility statement can be 
interrupted either in column 71 or after any comma. The continued portion of 
the utility control statement must begin in column 16 of the following statement. 
(Job control language continuations can begin in any column from 4 through 16, 
and do not require a non-blank character in column 72 for continued operand 
fields.) Comments can be placed on any card containing a complete or partial 
statement. However, when a card is included for the sole purpose of continuing a 
comment, the continuation must begin in column 16. 


Note: The IEBCOPY, IEBPTPCH, IEBGENER, IEBCOMPR, and IEBDG 
utility programs permit certain exceptions to these requirements (see the 
applicable program write-up). 


The utility contro] statements are discussed in detail, as applicable, in the 
remaining chapters. 


e A substitute name that represents two or more different device types (for 
example, DISK, meaning 3330 and 2314) cannot be processed by a utility 
program. 
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System Utility Programs 


Unless otherwise indicated in the description of a specific utility program, a 
temporary data set can be processed by a utility program only if the user 
specifies the complete name generated for the data set by the system (for 
example, DINAME=SYS68296.T00005 1.RP001.JOBTEMP.TEMPMOD). 


System utility programs manipulate collections of data and system control 
information. The system utility programs are: 


IEHATLAS, which is used to assign alternate tracks when defective tracks are 
indicated. 


IEHDASDR, which is used to initialize direct access volumes or to dump or 
restore data. 


IEHINITT, which is used to write standard labels on tape volumes. 


IEHIOSUP, which is used to update entries in the supervisor call library (VS1 
only). 


IEHLIST, which is used to list system control data. 
IEHMOVE, which is used to move or copy collections of data. 
IEHPROGM, which is used to build and maintain system control data. 


IFHSTATR, which is used to select, format, and write information about tape 
errors from the IFASMFDP tape or the SYS1.MAN data set. 


A system utility program is executed or invoked through the use of job control 
statements and utility control statements. 


System utility programs can be executed as jobs or can be invoked as subroutines 
by a calling program. The invocation of utility programs and the linkage 
conventions are discussed in ‘Appendix B: Invoking Utility Programs from a 
Problem Program.”’ 


When using system utility programs, be sure that: 


Each data set to be used by programs other than IEHPROGM, IEHMOVE, 
and IEHLIST is defined on a DD statement specifying the data set name and 
DISP=OLD. When updating activity is being performed by IEHPROGM, 
IEHMOVE, IEHLIST, or IEHDASDR in a multiprogramming environment, 
other tasks should not be allowed to access the data set being updated. (Refer 
to “Appendix C: DD Statements for Defining Mountable Devices”’ for 
precautions to be taken.) 


DD statements defining mountable devices specify that volumes mounted on 
those devices cannot be shared. 


Mountable volumes are not made available to the system until the user is 
requested by the system to mount the specified volumes. 


A reader procedure is used that will direct input and output data sets to 
volumes other than those which are to be modified by a system utility 
program. 


When executing a SCRATCH operation, the data set or volume being 
scratched is not being used by a program executing concurrently. 
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Data Set Utility Programs 


Data set utility programs manipulate partitioned, sequential, or indexed-sequential 
data sets provided as input to the programs. Data ranging from fields within a 
logical record to entire data sets can be manipulated. The data set utility 
programs are: 


¢ IEBCOMPR, which is used to compare records in sequential or partitioned 
data sets. 


e IEBCOPY, which is used to copy, compress, or merge partitioned data sets, to 
select or exclude specified members in a copy operation, and to rename 
and/or replace selected members of partitioned data sets. 


¢« IEBDG, which is used to create a test data set consisting of patterned data. 


¢ IEBEDIT, which is used to selectively copy job steps and their associated JOB 
Statements. 


¢ IEBGENER, which is used to copy records from a sequential data set or to 
convert a data set from sequential organization to partitioned organization. 


¢ IEBISAM, which is used to place source data from an indexed-sequential data 
set into a sequential data set in a format suitable for subsequent 
reconstruction. 


e IEBPTPCH, which is used to print or punch records that reside in a sequential 
or partitioned data set. 


e IEBTCRIN, which is used to construct records from the input data stream that 
have been read from the IBM 2495 Tape Cartridge Reader. 


e IEBUPDTE, which is used to incorporate changes to sequential or partitioned 
data sets. 


Data set utility programs can be executed as jobs or can be invoked as 
subroutines by a calling program. The invocation of utility programs and the 
linkage conventions are discussed in ““Appendix B: Invoking Utility Programs 
from a Problem Program.” 


4 


Independent Utility Programs 
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Independent utility programs operate outside, and in support of, the operating 
system. They are not supported, however, by the 3066 console, which is only 
used with the Model 165, System/370. If the 3066 is the only console available, 
execute independent utilities by following step 3b “Executing IBCDASDI and 
IBCDMPRS” below. The independent utility programs are: 


e IBCDASDI, which is used to initialize a direct access volume and to assign 
alternate tracks. 


e IBCDMPRS, which is used to dump and restore the data contents of a direct 
access volume. 


e ICAPRTBL, which is used to load the forms control and Universal Character 
Set buffers of a 3211 after an unsuccessful attempt to IPL with the 3211 
printer assigned as the output portion of a composite console. 
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Executing IBCDASDI and IBCDMPRS 


Executing ICAPRTBL 


IBCDASDI and IBCDMPRS are loaded as card decks or as card images on tape. 
Control statements for the requested program can follow the last card or card 
image of the program, or can be entered on a separate input device. To execute 
IBCDASDI or IBCDMPRS: 


1. Place the object program deck in the reader or mount the tape reel that 
contains the object program. 


2. Load the object program from the reader or tape drive by setting the load 
selector switches and pressing the console LOAD key. When the program is 
loaded, the wait state is entered and the console lights display the hexadecimal 
value FFFF. 


3. Define the control statement input device in one of the following ways: 


(a) Press the REQUEST key of the console typewriter and, in response to the 
message “DEFINE INPUT DEVICE”, enter “INPUT= xxxx,cuu”’. The 
xxxx is the device type, c is the channel address, and uu is the unit 
address. The device type can be 1402, 1442 (VS1 only), 2400, 2501, or 
2540. 


(b) If the console typewriter is not available, enter at storage location 0110 
(hexadecimal): 1 cuu for a 1442 Card Read Punch; 2cuu for a 2400 
9-track tape unit; or Ocuu for a 2540 Card Read Punch, 2501 card 
reader, 3410 tape, or 3420 tape. Press the console INTERRUPT key. 


4. Control statements are printed on the message output device. At the end of 
the job, “END OF JOB” is printed on the message output device, and the 
program enters the wait state. 


ICAPRTBL must be loaded from a card reader. Control statements must follow 
the last card of the program. Only one printer can be initialized each time the 
program is executed. 


To execute ICAPRTBL: 
1. Mount the correct train on the printer and ready the printer. 


2. Place the object program deck and the control cards in the card reader. Ready 
the reader and press the END OF FILE key. 


3. Load the object program from the reader by setting the load selector switches 
and pressing the console LOAD key. 


Wait state codes will be displayed in the address portion of the PSW for normal 
termination and for input/output, system or control card errors. Code BO1 is 
issued for normal termination; BO2 through BO7 are issued for control card 
errors; BOA through BOC are issued for system errors; and B11 through B1D are 
issued for input/output errors. Table 2 shows these codes and their meanings. 
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Table 2. ICAPRTBL Wait-State Codes 


Code Meaning Code Meaning 
BOI Visually check the train B12. ~~ Reader not ready. 
image printed on the 3211. B13 ~—Reader unit check (display low 
BO2 Missing control card or main storage location 2 through 
control card out of order. 7 for sense information). 
BO3 Incorrect JOB statement. Bi4 — Reader channel error. 
BO4 Incorrect DFN statement. B15 No device end on reader. 
BOS Incorrect UCS statement. B19 Printer not online. 
B06 ~=—s Incorrect FCB statement. BIA _ Printer not ready, 
BO7 ~=Incorrect END statement. BIB _ Printer unit check (display low 
BOA External interrupt. main storage location 2 through 
BOB ‘Program check interrupt. 7 for sense information). 
BOC Machine check interrupt. BIC Printer channel error. 
Bil Reader not online. BID No device end on printer. 
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IBCDASDI Program 


IBCDASDI is an independent utility used to initialize direct access volumes for 
use and to assign alternate tracks on direct access storage volumes. (See 
“Introduction” for general independent utility information.) IBCDASDI jobs can 
be performed continuously by stacking complete sets of control statements. 


Initializing a Direct Access Volume 


IBCDASDI can be used to initialize a direct access volume. A volume can be 
initialized with or without surface analysis, a test for defective tracks; however, a 
surface analysis should be performed when a volume is initialized for the first 
time. 


When a volume is initialized, IBCDASDI: 


e Checks for tracks that have been previously designated as defective (flagged) 
and have had alternates assigned. This test must be suppressed when a disk is 
initialized with surface analysis for the first time. This test must not be 
suppressed when a volume is initialized without surface analysis. 


¢« Automatically assigns alternates, if necessary, when a volume is initialized with 
surface analysis. Tracks that are available for use as alternates are checked 
first. 


e Writes a track descriptor record (record 0) and erases the remainder of each 
track. When a volume is initialized with surface analysis, IBCDASDI also 
writes a standard home address. 


« Writes IPL records on track O (records 1 and 2). 


e Writes volume label on track 0 (record 3) and provides space for additional 
records, if requested. 


e Constructs and writes a volume table of contents (VTOC). 


¢ Writes an IPL program, if requested. When a volume is initialized with surface 
analysis, the IPL program is written on track 0 for 2305, 3330, or 2319 
volumes. When a volume is initialized without surface analysis, the IPL 
program is written on track O for 2305, 3330, 2319, or 3330 volumes. 


Note: Defective tracks are flagged and alternate tracks are assigned when the 
3330 storage volumes are initialized at the factory. An IBCDASDI job to 
initialize a 3330 will not perform a surface analysis. The quick DASDI, which 
can be performed on a 3330 volume, includes: (1) reading alternate tracks and 
decreasing the total count of the alternates by one when an alternate is found 
defective or assigned; (2) writing a volume label and VTOC; and (3) writing 
IPLTXT, if requested. Record 0 can be rewritten on each track in each case. 
Note that surface analysis is not performed and the home address is not written 
on the primary tracks. The BYPASS and FLAGTEST options of the DADEF 
statement are ignored. (See ‘““DADEF Statement’’ below.) 


Assigning an Alternate Track 


IBCDASDI can be used to: (1) test a track and, if necessary, assign an alternate 
or (2) bypass testing and automatically assign an alternate. 


If testing is performed, an alternate track is assigned for any track found 
defective. If the defective track is an unassigned alternate, it is flagged to prevent 
its future use. The alternate track address is made known to the operator. 
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Input and Output 


Control 


If a track is tested and not found to be defective, no alternate is assigned. The 
operator is notified by a message. 


If testing is bypassed, an alternate track can be assigned for the specified track 
or its alternate, whether it is defective or not. If the specified track is an 
unassigned alternate, it is flagged to prevent its future use. 


Note: No test for defective tracks is performed for 3330 volumes; an alternate 
track is automatically assigned. 


IBCDASDI uses as input a control data set, which consists of utility control 
Statements. 


IBCDASDI produces as output an initialized direct access volume and a message 
data set. 


IBCDASDI is controlled by utility control statements. Because IBCDASDI is an 
independent utility, operating-system job control statements are not used. 


Utility Control Statements 


JOB Statement 


MSG Statement 
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IBCDASDI utility control statements in the order in which they must appear are: 


e« JOB statement, which is used to indicate the beginning of an IBCDASDI job. 


e MSG statement, which is used to define an output device for operator 
messages. 


e DADEF statement, which is used to define the volume to be initialized. 


¢« VLD statement, which contains information for constructing an initial volume 
label and for allocating space for additional labels. 


e VTOCD statement, which contains information for controlling the location of 
the volume table of contents. 


e IPLTXT statement, which is used to separate utility control statements from 
any IPL program text statements. 


e GETALT statement, which is used to assign an alternate track on a volume. 
e END statement, which is used to indicate the end of an IBCDASDI job. 


« LASTCARD statement, which is used to end a series of stacked IBCDASDI 
jobs. 


The JOB statement indicates the beginning of an IBCDASDI job. 
The format of the JOB statement is: 

{ label ] JOB f ‘user-information | 
JOB must be preceded and followed by at feat one blank. 


The MSG statement defines an output device for operator messages. It follows 
the JOB statement and precedes any function-definition statements. 


DADEF Statement 


The format of the MSG statement is: 


tote tee 


where: 
TODEV= xxxx 
specifies the type of output device to receive messages, for example, 1403. 


The devices that can be specified are 1403, 1443, 1052, 2400, 3210, and 
3211: 


TOADDR= cuu 
specifies the channel number, c, and unit number, uu, of the message output 
device. 


The DADEF statement defines the direct access volume to be initialized. 


The format of the DADEF statement is: 


where: 


TODEV= xxxx 
specifies the type of the direct access device to be initialized, for example, 
3330. Note that the 2319 disk is functionally equivalent to the 3330 disk. To 
use a 2319, specify 3330 in the TODEV parameter. 


TOADDRe= cuu 
specifies channel number, c, and unit number, wu, of the device. 
IPL=YES 


specifies that an IPL program is to be written on the volume. An IPL 
initialization program must be written on a device to be used for system 
residence. If IPL is omitted, no IPL program is written. 


VOLID= 
specifies whether a volume serial number check is to be made. These values 
can be coded: 


serial 
specifies the volume serial number of the volume to be initialized. If serial 
does not match the volume serial number found On the volume to be 
initialized, the operator is notified and the job is terminated. 


SCRATCH 
specifies that no volume serial number check is to be made. 


FLAGTEST=NO 
specifies that no check is to be made for previously flagged tracks on a disk 
volume before surface analysis is performed. FLAGTEST=NO should be 
specified when the disk recording surface is initialized for the first time. 
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VLD Statement 


VTOCD Statement 
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PASSES= n 
specifies the number of passes per track to be made in checking for defective 
tracks. PASSES is valid when surface analysis is to be performed or when a 
quick DASDI is to be performed on a 3330 volume. The value n can be 0 
through 255. The 0 specification indicates that a quick DASDI is to be 
performed on a 3330 volume. For a 3330 volume, a non-zero value causes 
record 0 to be written on each track. No check is made for defective tracks 
on a 3330. A specification of 1 through 255 indicates the number of passes to be 
made per track for volumes other than a 3330 volume. If PASSES is 
omitted, one pass is made per track. 


BYPASS=YES 
specifies that no check is to be made for defective tracks. If BYPASS is 
omitted, tracks are checked and those found defective are automatically 
assigned alternates. This parameter applies only when surface analysis is not to 
be performed. 


MODEL= n 
specifies a decimal model number (1 or 2). This parameter corresponds to the 
2305-1 and 2305-2, respectively. MODEL is required when a 2305 is to be 
initialized. 


The VLD statement contains information for constructing an initial volume label 
and for allocating space for additional labels. 


The format of the VLD statement is: 


where: 


NEWVOLID= serial 
specifies a one- to six-character volume serial number. 


VOLPASS= 
specifies the value of the volume security bit. These values can be coded: 


0 
specifies that the volume is not security protected. If VOLPASS is omitted, 
0 is assumed. 


specifies that the volume is security protected. 


OWNERID= xxxxxxxxxx 
specifies a one- to ten-character field that identifies the owner of the volume. 
If OWNERID is omitted, no identification is given. 


ADDLABEL= n 
specifies the total number of additional labels for which space is to be 
allocated. The value of n can be 1 through 7. If ADDLABEL is omitted, 0 is 
assumed. 


The\VTOCD statement contains information for controlling the location of the 
volume table of contents (VTOC). 
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IPLTXT Statement 


GETALT Statement 


The format of the VTOCD statement is: 
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STRTADR= nnann 
specifies the one- to five-byte track address, relative to the beginning of the 
volume, at which the VTOC is to betin. The VTOC cannot occupy track 0 or 
any alternate track. 


EXTENT= annn 
specifies the length (number of tracks) of the VTOC. 


Table 3 shows the number of VTOC entries per track for each device type. 


Table 3. VITOC Entries per Track 


Device VIOC Entries per Track 


3330 25 
2519 PEs) 
2305-1] 18 
2305-2 34 
3330 39 


The IPLTXT statement separates utility control statements from IPL program 
text statements. It is required only when IPL text is included. 


ie format of the IPLTAT statement t is: 


When IPL text is caciieedl END must start in lieih 2. See “END Seance 
below. 


The GETALT statement is used to assign an alternate track on a volume. Any 


number of alternate tracks can be assigned in a single job by including a 
GETALT statement for each track. 


Note: A GETALT statement that applies to a 3330 device causes an alternate 
track to be assigned automatically without testing. 


eS format of the GETALT statement is: 
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TODEV= xxxx 
specifies the device type of the direct access device. 
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END Statement 


LASTCARD Statement 
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TOADDR= cuu 
specifies the channel number, c, and unit number, uu, of the direct access 
device. 


TRACK= cccchhhh 
specifies the address of the track for which an alternate is requested, where 
cccc is the cylinder number and shhh is the head number. 


VOLID= serial 
specifies the volume serial number of the volume to which an alternate track is 
to be assigned. If seria/ does not match the volume serial number found on 
this volume, the operator is notified and the job is terminated. 


FLAGTEST=NO 
specifies that no check is to be made for a previously flagged track before a 
surface analysis for a disk volume is performed on this track. This parameter is 
used when testing before assigning an alternate. 


PASSES= n 
specifies the number of passes, n, to be made when performing a surface 
analysis on this track. The value of n can be 1 through 255. If PASSES is 
omitted, one pass is made. (If, however, the GETALT statement applies to a 
3330 volume, an alternate track is assigned without testing; the PASSES 
parameter is ignored.) This parameter is used when testing before assigning an 
alternate. 


BYPASS=YES 
specifies that no defective-track check is to be made. If BYPASS is omitted, 
the program assigns an alternate only if it finds that the specified track is 
defective. 


MODEL= n 
specifies a decimal model number (1 or 2). This parameter corresponds to the 
2305-1 and 2305-2, respectively. MODEL is required when a 2305 is to be 
initialized. 
The GETALT function should not be used immediately after a RESTORE 
operation that did not complete successfully. Before using GETALT in such a 
case, reinitialize the volume, if possible. 


The END Statement denotes the end of job. It appears after the last 
function-definition statement. 


The format of the END statement is: 


eee ta . 


END must be preceded and followed by at least one blank. 


The LASTCARD statement is required only when an IBCDASDI job or a series 
of stacked IBCDASDI jobs is followed by other statements on the control 
statement input device. The LASTCARD statement must follow the last END 
statement applying to an IBCDASDI job. 


The format of the LASTCARD statement is: 
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IBCDASDI Example 1 


IBCDASDI Example 2 


The examples that follow illustrate some of the uses of IBCDASDI. Table 4 can 
be used as a quick reference guide to IBCDASDI examples. The numbers in the 
‘‘Example”’ column point to examples that follow. 


Table 4. IBCDASDI Example Directory 


Operation Comments Example 
Initialize A 2305 volume is to be initialized with 

surface analysis. ] 
Initialize A 2305 volume ts to be initialized without 

surface analysis. 2 
Initialize A 3330 volume to be used as the system 

residence volume is to be initialized. An IPL 

program ts included in TXT format. 3 
Assign alternate Three alternate tracks are to be assigned 
tracks on a 3330 volume. 4 


In this example, a 2305 volume is initialized for the first time. 
A surface analysis is performed with the initialization. 


The example follows: 


INDY, JOB: *INETLALLZE 2305" 
MSG TODEV=1403,TOADDR=O00E 
DADEF TODEV=2305, TOADDR=140, VOLID=SCRATCH, FLAGTEST=NO 
VLD NEWVOLID=111111 
VTOCD STRTADR=50, EXTENT=10 
END 


The control statements are discussed below: 

¢ JOB initiates the IBCDASDI job. 

e MSG defines the 1403 on channel 0, unit OE, as the output message device. 
e DADEF specifies that a 2305 volume on channel 1, unit 40, is to be 


initialized. Because the volume is being initialized for the first time, no check is 


to be made for previously flagged tracks. 


e VLD specifies 111111 as the volume serial number of the volume to be 
initialized. 

« VTOCD specifies the starting address and length in tracks of the volume table 
of contents. 


In this example, a 2305 volume is initialized for the first time. No surface 
analysis is performed with the initialization. 


The example follows: 


INIT JOB INITIALIZE 3330 
MSG TODEV=1403,TOADDR=O00E 
DADEF TODEV=2305,TOADDR=140, VOLID=SCRATCH, BYPASS=YES 
VLD NEWVOLID=333000 
VTOCD STRTADR=1,EXTENT=3 
END 


The control statements are discussed below: 


| + DADEF specifies that a 2305 volume is to be initialized and specifies the 


channel and unit number. No check is to be made for the volume serial 
number or for defective tracks. 
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IBCDASDI Example 3 


IBCDASDI Example 4 
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VLD specifies the volume serial number of the volume to be initialized. 


VTOCD specifies that the volume table of contents is to begin on track 1 and 
is to extend over three tracks. 


END specifies the end of the IBCDASDI job. } 


| In this example, a 3330 volume is initialized for later use as a system residence 
volume. An IPL program is included in standard TXT format. 


The example follows: 


INIT JOB: ‘INITIALIZE 3330" 


MSG TODEV=1403,TOADDR=00E 
DADEF TODEV=3330,TOADDR=150,IPL=YES 

VLD NEWVOLID=P10000,OWNERID=BROWN , ADDLABEL=2 
VTOCD STRTADR=2, EXTENT=9 
EPEAT 


(IPL program text statements) 


END 


The control statements are discussed below: 


DADEF specifies that a 3330 volume is to be initialized and specifies the 
channel number and unit number. An IPL program is to be included. 


VLD specifies a volume serial number and owner identification for the volume 
to be initialized. It also specifies that space is to be allocated for two 
additional labels. 


VTOCD specifies that the volume table of contents is to begin on track 2 and 
is to extend over nine tracks. 


IPLTEXT specifies the beginning of IPL program text statements. ) 


END specifies the end of IPL program text statements. Because IPL text is 
included, END begins in column 2. 


| In this example, three alternate tracks are assigned to a 3330 volume, without 
reinitialization of the volume. The check for a defective track is bypassed when 
the first two of the three tracks are assigned. 


The example follows: 


72 
ALTRK JOB ASSIGN ALTERNATE TRACKS ON 3330 
MSG TODEV=1052, TOADDR=009 
STMT1  GETALT TODEV=3330,TOADDR=150,VOLID=P20000, ( Vc 
BY PASS=VYES , TRACK=O06F0001 
STMT2 GETALT TODEV=3330,TOADDR=150,VOLID=P20000, pas 
BYPASS=YES , TRACK=00910004 
STMT3 GETALT TODEV=3330, TOADDR=150, VSc 


TRACK=004B0007 , VOLID=P20000 
END 


The control statements are discussed below: 


The first and second GETALT statements bypass the check for defective 
tracks. 


The third GETALT statement causes the check for a defective track to be 
made because BYPASS js not included. 


IBCDMPRS Program 


C IBCDMPRS is an independent utility used to dump and restore data on direct 
access volumes. (See “Introduction” for general independent utility information. ) 


The data contents of a direct access volume (all data except the home address) 

| can be dumped to 2305, 2314, 2319, 3330, or tape volumes and restored to a 
direct access volume that resides on the same type of device as the source 
volume. Both the source volume and the volume to which data is to be restored 
must have been initialized according to operating system specifications. 
IBCDMPRS is useful for preparing transportable copies and backup copies of 
direct access volumes. 


Input and Output 
IBCDMPRS uses as input: 
e A control data set, which contains utility control statements. 
e« A data set to be dumped to tape or to be restored to a direct access volume. 
IBCDMPRS produces as output: 
« A data set dumped to tape or a data set restored to a direct access volume. 


e A message data set. 


Control 


( IBCDMPRS is controlled by utility control statements. Because IBCDMPRS is an 
independent utility, operating-system job control statements are not used. 


Utility Control Statements 
IBCDMPRS utility control statements are: 


e JOB statement, which is used to begin an IBCDMPRS job. 


e MSG statement, which is used to define an output device for operator 
messages. 


e DUMP statement, which is used to identify the volume to be dumped and the 
receiving volume. 


¢ VDRL Statement, which is used to specify the upper and lower track limits of 
a partial dump. 


¢ RESTORE statement, which is used to identify the source volume whose data 
is to be restored and the receiving volume. 


¢ END statement, which is used to indicate the end of an IBCDMPRS job. 


JOB Statement 
The JOB statement indicates the beginning of a job. 


The format of the JOB statement is: 


JOB must be preceded and followed by at least one blank. 
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MSG Statement 


DUMP Statement 
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The MSG statement defines an output device for operator messages. It follows 
the JOB statement and precedes any function-definition statements. 
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where: 


TODEV= xxxx 
specifies the type of the output device to receive messages, for example, 1403. 
The devices that can be specified are 1403, 1443, 1052, 2400, 3210, and 
3211. 


TOADDR= cuu 
specifies the channel number, c, and unit number, uu, of the message output 
device. 


The DUMP statement is used to identify both the source volume whose contents 
are to be dumped and the receiving volume. The data contents of the entire 
source volume are dumped, including any data on alternate tracks. If both the 
source and receiving volumes reside on 2314, 2319, or 3330 volumes, the 
receiving volumes is an exact replica of the source volume. 


The format of the DUMP statement is: 


Pe oF, > ow s —-l 
diy’ < rei < 3 T - wy by grea et] ~ 


FROMDEV= xxxx 
specifies the type of the source device, for example, 3330. 


FROMADDRe=  cuu 
specifies channel number, c, and unit number, wu, of the source device. 


TODEV= xxxx 
specifies the type of the receiving device, for example, 2400. If the receiving 
device is a tape unit and no MODE parameter is specified, the data is written 


at the highest density supported by the device. (For 7-track tape, the default 
mode is 93.) 


TOADDR= cuu 
specifies the channel number, c, and unit number, uu, of the receiving 
device. 


VDRL Statement 


VOLID= serial |, serial}... 
specifies the volume serial numbers of the receiving volumes to which data is 
to be dumped. VOLID is required when the receiving volume has been 
initialized according to operating-system specifications. If serial does not 
match the volume serial number found on the receiving volume, the operator is 
notified and the job is terminated. If VOLID is not specified and the receiving 
volume contains a volume serial number, the operator is notified. 


MODE= mm 
specifies the bit density for data written onto the receiving magnetic tape 
volume. This parameter is applicable to 7-track tape units and to 9-track tape 
units with density selections of 800 and 1600 bits per inch. Valid modes for 
7-track tape are shown in Table 5. For 9-track tape with density selections of 
800 and 1600 bits per inch, the mode settings are CB and C3, respectively. 
(Only those modes that set the data converter on are accepted.) If the 
receiving device is not a tape unit, the MODE parameter is ignored. If the 
receiving device is a tape drive but no mode is specified, the data is written at 
the highest density supported by the device. 


MODEL= n 
specifies a decimal model number (1 or 2) for a 2305. This parameter is 
applicable only when a 2305 is specified. If MODEL is omitted, 2305-1 is 
assumed. 


Note: The 2319 disk is functionally equivalent to the 2314 disk. To use the 
2319, specify 2314. 


Dump time can be minimized by selecting devices assigned to different channels. 
For example: 


DUMP FROMDEV=3330,FROMADDR=150, TODEV=2400, TOADDR=282 


Table 5 shows valid modes for 7-track tape that can be entered for the MODE 
parameter. , 


Table 5. Valid 7-Track Tape Unit Modes in IBCDMPRS 


Mode Density Data 

(mm) (bits per inch) Translator Converter Parity 
13 200 Off On Odd 
Se) 556 Off On Odd 
oe 800 Off On Odd 


The VDRL (volume dump/restore limits) statement is used to specify the upper 
and lower limits of a partial dump. If a track within these limits has had an 
alternate assigned to it, the data on the alternate track is included in the dump. 
When the VDRL statement is used, it must be preceded by a DUMP statement 
and must be followed by an END statement. 

The format of the VDRL statement ts: 


ae wy v2 
boss ta) 


where: 


BEGIN= nannn 
specifies a one- to five-byte relative track address that identifies the first track 
to be dumped. 
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END= nnnnn 
specifies the relative track address of the last track to be dumped. If only one 
track is to be dumped, this address is the same as the beginning address. If 
END is omitted, the last track of the volume, excluding those tracks reserved | 
as alternates, is assumed to be the upper limit. J 


RESTORE Statement 


The RESTORE statement is used to identify both the source volume whose data 
contents are to be restored and the receiving volume. 


Note: IBCDMPRS can be used to restore a tape created by IEHDASDR. 
Conversely, IEHDASDR can be used to restore a tape created by IBCDMPRS. 


The format of the RESTORE statement is: 


3 
- 


FROMDEV= xxxx 
specifies the type of the source device, for example, 2400. 


FROMADDR= cuu 
specifies the channel number, c, and unit number, uu, of the source device. 


TODEV= xxxx 
| specifies the type of the receiving device, for example, 3330. This device type 
must be the same as the device containing the volume originally dumped. 


TOADDR= cuu 
specifies the channel number, c, and unit number, wu, of the receiving 
device. 


VOLID= serial 
specifies the volume serial number of the receiving volume. If serial does not 
match the volume serial number found on the receiving volume, the operator is 
notified and the job is terminated. 


MODE= mm 
specifies the bit density for data written to the receiving tape volume. This 
parameter must match the mode specified when data was written to the source 
volume. MODE should not be specified if the source and receiving volumes 
are not tape or if MODE was not specified when data was written to the 
source volume. Valid modes are shown earlier in Table 5. (Only those modes 
that set the data converter on are accepted.) For 9-track tape units with 
density selections of 800 and 1600 bits per inch, the mode settings are CB 
and C3, respectively. 


MODEL= n 


specifies a decimal model number (1 or 2) for a 2305. If MODEL is omitted, 
2305-1 is assumed. 


Restore time can be minimized by selecting devices assigned to different 
channels. For example: ™ 


| RESTORE FROMDEV=2400,FROMADDR=282, TODEV=3330, TOADDR=150 
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L 


END Statement 


IBCDMPRS Examples 


IBCDMPRS Example 1 


IBCDMPRS Example 2 


The END statement marks the end of job. It appears after the last 
function-definition statement. 


— 


The format 


DPS 
ve lets 


of the END statement is: 


END must be preceded and followed by at least one blank. 


The examples that follow illustrate some of the uses of IBCDMPRS. Table 6 can 
be used as a quick reference guide to the examples. The numbers in the 
““Example”’ column point to examples that follow. 


Table 6. IBCDMPRS Example Directory 


Operation Comments Example 
DUMP A direct access volume is to be 

dumped to a tape volume. | 
RESTORE A data set dumped to tape is to be 

restored to a direct access volume. 2 


In this example, a direct access volume is dumped to a tape volume. 


The example follows: 


a2 
DUMP JOB DUMP 3330 ONTO TAPE 
MSG TODEV=3210,TOADDR=009 
DUMP FROMDEV=3330,FROMADDR=150, ‘eve 
TODEV=2400 , TOADDR=280 
END 
In this example, dumped data is restored to a direct access volume. 
The example follows: 
42 


RESTORE JOB RESTORE 3330 FROM TAPE 
MSG TODEV=3210, TOADDR=009 
RESTORE FROMDEV=2400, FROMADDR=280, TODEV=3330, ee 
TOADDR=150, VOLID=PZ1111 
END 
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ICAPRTBL Program 


Input and Output 


Control 


ICAPRTBL is an independent utility used to load the Universal Character Set 
(UCS) buffer and the forms control buffer (FCB) for an IBM 3211 Printer. (See 
“Introduction” for general independent utility information.) 


ICAPRTBL is used when the 3211 is assigned as the output portion of a 
composite console and an unsuccessful attempt has been made to initialize the 
operating system because the UCS and FCB buffers contain improper bit 
patterns. I[CAPRTBL is used to properly load the buffers so the operating system 
can be initialized. 


Note: When an operable console printer-keyboard is available, the buffers are 
loaded under the control of the operating system. 


ICAPRTBL uses as input utility control statements that contain images to be 
loaded into the Universal Character Set and/or forms control buffer. ICAPRTBL 
produces as output properly loaded UCS and FCB buffers. 


ICAPRTBL is controlled by utility control statements. Because ICAPRTBL is an 
independent utility, operating system job control statements are not used. 


Utility Control Statements 


JOB Statement 


DFN Statement 


ICAPRTBL utility control statements are: 
e JOB statement, which is used to indicate the beginning of an ICAPRTBL job. 
e DEN statement, which is used to define the address of the 3211. 


e UCS statement, which contains an image of the characters to be loaded into 
the UCS buffer. 


¢ FCB statement, which defines the image to be loaded into the FCB. 
¢ END statement, which is used to indicate the end of an ICAPRTBL job. 


The JOB statement indicates the beginning of an ICAPRTBL job. 
The format of the JOB statement is: 

[ label] JOB [ user-information | 
JOB must be preceded and followed by at least one blank. 


The DFN statement is used to define the address of the 3211 and to specify that 
lowercase letters are to be printed in uppercase when the lowercase print train is 
not available. 


The format of the DFN statement ts: 


DFN ADDR= cuu, FOLD= {Y } _ | meee ss 
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where: 


ADDR= cuu 
specifies the channel number, c, and unit number, uu, of the 3211. 
FOLD= 


specifies whether lowercase letters are to be printed as uppercase letters when 
the lowercase print train is not available. These values can be coded: 


Y 
specifies that lowercase letters are to be printed as uppercase letters when 
the lowercase print train is not available. 


N 
specifies that lowercase letters are not to be printed as uppercase letters. 


UCS Statement 
The UCS statement contains an image to be loaded into the UCS buffer. 


The format of the UCS statement is: 


where: 


ucsname 
is a one- to eight-character alphameric name. This name is printed on the 
printer to serve as a reference to the print train being used. 


ucs-image 
specifies characters to be loaded into the UCS buffer. The characters must be 
contained in columns 16 through 71. The first UCS statement contains the 
first 56 characters; subsequent statements contain continuations of the image 
to be loaded into the UCS buffer. 


FCB Statement 


The FCB statement defines the image to be loaded into the forms control buffer. 
The FCB statement may precede or follow the UCS statement. 


The format of the FCB statement is: 


where: 


fcbname 
specifies a one- to eight-character name of the image loaded into the forms 
control buffer. The actual image loaded into the buffer is not affected by this 
name, but to serve as a meaningful reference when printed on the printer, 
fcbname should be the same as the FCB image being used. 


LPI= 
specifies the number of lines per inch that will be printed on the document. 
These values can be coded: 


6 
specifies that six lines per inch will be printed. 


8 
specifies that eight lines per inch will be printed. 
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LNCH= 
specifies the channels of the FCB image. Each set of parentheses must contain 
the line number (1-280), a comma, and the channel number (1-12) to be 
assigned to that line. One or all of the 12 channels may be assigned in any 
order. Each set must be separated by commas and the entire group surrounded 
by parentheses. 


FORMEND= x 
specifies the number of lines (maximum 180) on the printer form. For an 11 
inch form, spacing six lines per inch, x must be 66. 
END Statement 
The END statement signals the end of the ICAPRTBL job. 


The format of the END statement is: 


END must be preceded and followed by at least one blank. 


ICAPRTBL Example 


In this example, an All UCS image and an FCB image are loaded into the UCS 
and FCB buffers. 


The example follows: 


v2 
JOB LOAD A111 IMAGE 
DFN ADDR=002,FCLD=N 
All UCS 1<.=IHGFEDCBA*$-ROPONMLKJ&%, &ZYXWVUTS/@#0987654321<.=IHGF 
EDCBA*$—ROPONMLKJ %, EZYXWVUTS/0#0987654321<.=IHGFEDCBA*$- 
RQPONMLKJ%, &ZYXWVUTS/0#0987654 321<.=IHGFEDCBA* $-RQPONMLK 
J%, &EZYXWVUTS/0#0987654321<.=IHGFEDCBA* $-ROPONMLKJ%, &ZYXW 
VUTS/0#0987654321<.=IHGFEDCBA*$—-ROQPONMLKJ %, &ZYXWVUTS/a#0 
987654321<.=ihgfedcba*$-rqponmlkj%, &zyxwvuts/23098765432 
1<.=IHGFEDCBA*$-RQPONMLKJ %, &EZYXWVUTS/@#0987654321<.=IHGF 
EDCBA* $-RQPONMLKJ %, &ZYXWVUTS/@#098765432 
STD2 FCB LPI=6, 


LNCH=((4, ay E102 eC 16 33 C22 28-5) (346 a7) Ave 
(46,8),(52,10),(58,11),(64,12),(66,9)) 
END 


The control statements are discussed below: 


¢ DFN specifies the channel and unit number of the 3211 and specifies that 
lowercase letters are not to be printed as uppercase letters when the lowercase 
print train is not available. 


e UCS specifies the characters to be loaded into the UCS buffer. 


¢ FCB specifies the values to be loaded into the forms control buffer. 
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IEBCOMPR Program 


IEBCOMPR is a data set utility used to compare two sequentially organized or 
two partitioned data sets at the logical-record level to verify a backup copy. 
Fixed, variable, or undefined records from blocked or unblocked data sets or 
members can be compared. (See “Introduction” for general data set utility 
information. ) 


Two sequential data sets are considered equal, that is, are considered to be 
identical, if: 


e The data sets contain the same number of records. 
e Corresponding records and keys are identical. 


If these conditions are not met, an unequal comparison results. If records are 
unequal, the record and block numbers, the names of the DD statements that 
define the data sets, and the unequal records are listed in a message data set. 
Ten successive unequal comparisons terminate the job step unless a user routine 
is provided to handle error conditions. 


Two partitioned data sets are considered equal if: 

e Corresponding members contain the same number of records. 

e Note lists are in the same position within corresponding members. 
e Corresponding records and keys are identical. 


If these conditions are not met, an unequal comparison results. If records are 
unequal, the record and block numbers, the names of the DD statements that 
define the data sets, and the unequal records are listed in a message data set. 
After ten successive unequal comparisons, processing continues with the next 
member unless a user routine is provided to handle error conditions. 


Partitioned data sets can be compared only if all the names in one or both of the 
directories have counterpart entries in the other directory. The comparison is 
made on members identified by these entries and corresponding user data. 


Figure 3 shows the directories of two partitioned data sets. Directory 2 contains 
corresponding entries for all the names in Directory 1; therefore, the data sets 
can be compared. 


Directory 2 | 
@BOEDE FIGH 
1 J Kub 


Directory 1 


Figure 3. Partitioned Directories Whose Data Sets Can Be Compared Using 
IEBCOMPR 


Figure 4 shows the directories of two partitioned data sets. Each directory 
contains a name that has no corresponding entry in the other directory; 
therefore, the data sets cannot be compared, and the job step is terminated. 
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Input and Output 


Control 
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Directory 1 
ABGFHIJ 


Directory 2 
ABFGHIJ 


Figure 4. Partitioned Directories Whose Data Sets Cannot Be Compared Using 
IEBCOMPR 


User exits are provided for optional user routines to process user labels, handle 
error conditions, and modify source records. See ‘Appendix A: Exit Routine 
Linkage”’ for a discussion of the linkage conventions to be followed when user 
routines are used. 


At the completion or termination of IEBCOMPR, the highest return code 
encountered within the program is passed to the calling program. 


IEBCOMPR uses the following input: 
« Two sequential or two partitioned data sets to be compared. 


« A control data set that contains utility control statements. This data set is 
required if the input data sets are partitioned or if user routines are used. 


IEBCOMPR produces as output a message data set that contains informational 
messages (for example, the contents of utility control statements), the results of 
comparisons, and error messages. 


IEBCOMPR provides a return code to indicate the results of program execution. 


The return codes and their meanings are: 

e QO, which indicates successful completion. 

e 08, which indicates an unequal comparison. Processing continues. 

e 12, which indicates an unrecoverable error. The job step is terminated. 


e 16, which indicates that a user routine passed a return code of 16 to 
IEBCOMPR. The job step is terminated. 


IEBCOMPR is controlled by job control statements and utility control 
Statements. The job control statements are required to execute or invoke 
IEBCOMPR and to define the data sets that are used and produced by 
IEBCOMPR. The utility control statements are used to indicate the input data 
set organization (that is, sequential or partitioned), to identify any user routines 
that may be provided, and to indicate whether user labels are to be treated as 
data. 


nat 


Job Control Statements 
Table 7 shows the job control statements necessary for using IEBCOMPR. 


Table 7. IEBCOMPR Job Control Statements 


( Statement Use 
JOB Initiates the job. 
EXEC Specifies the program name (PGM=IEBCOMPR) or, if the job control 


Statements reside in a procedure library, the procedure name. 


SYSPRINT DD Defines a sequential message data set, which can be written to a system 
Output device, a tape volume, or a direct access volume. 


SYSUTI DD Defines an input data set to be compared. 
SYSUT2 DD Defines an input data set to be compared. 


SYSIN DD Defines the control data set or specifies DUMMY if the input data sets are 
sequential and no user routines are provided. The control data set normally 
resides in the input stream; however, it can be defined as a member within a 
library of partitioned members. 


One or both of the input data sets can be passed from a preceding job step. 


Input data sets residing on different device types can be compared. Input data 
sets with a sequential organization written at different densities can be compared. 


Restrictions 


e The SYSPRINT DD statement must be present for each use of IEBCOMPR. 
e The SYSIN DD statement is required. 


« The logical record lengths of the input data sets must be identical; otherwise, 
unequal comparisons result. The block sizes of the input data sets can differ; 
however, block sizes must be multiples of the logical record length. 


| ¢« The block size specified in the SYSPRINT DD statement must be a multiple 
of 121. The block size specified in the SYSIN DD statement must be a 
multiple of 80. 


Utility Control Statements 
The utility control statements used to control IEBCOMPR are: 


e COMPARE statement, which is used to indicate the organization of a data 
set. 


¢ EXITS statement, which is used to identify user exit routines to be used. 


« LABELS statement, which is used to indicate whether user labels are to be 
treated as data by IEBCOMPR. 


COMPARE Statement 
The COMPARE statement is used to indicate the organization of data sets to be 
compared. 


The format of the COMPARE statement is: 


[label] COMPARE TYPORG= (es) ; 


where: 


TYPORG= 
specifies the organization of the input data sets. If TYPORG is omitted, input 
data sets are assumed to be sequentially organized. The values that can be 


( coded are: 
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EXITS Statement 


LABELS Statement 
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PS 
specifies that the input data sets are sequential data sets. 


PO 
specifies that the input data sets are partitioned data sets. 


The COMPARE statement, if included, must be the first utility control 
statement. COMPARE is required if the EXITS or LABELS statement is used or 
if the input data sets are partitioned data sets. 


The EXITS statement is used to identify any user exit routines to be used. 


The format of the EXITS statement is: 


where: 


INHDR= routinename 
specifies the symbolic name of a routine that processes user input header 
labels. 


INTLR= routinename 
specifies the symbolic name of a routine that processes user input trailer 
labels. 


ERROR2= routinename 
specifies the symbolic name of a routine that is to receive control after each 
unequal comparison for error handling. If this parameter is omitted and ten 
consecutive unequal comparisons occur while IEBCOMPR is comparing 
sequential data sets, processing is terminated; if the input data sets are 
partitioned, processing continues with the next member. 


PRECOMP2= routinename 
specifies the symbolic name of a routine that processes logical records 
(physical blocks in the case of VS or VBS records longer than 32K bytes) 
from either or both of the input data sets before they are compared. 


The EXITS statement is required if a user exit routine is to be used. If more than 
one valid EXITS statement is included, all but the last EXITS statement are 
ignored. For a discussion of the processing of user labels as data set descriptors, 
see ““Appendix E: Processing User Labels.” 


The LABELS statement specifies whether user labels are to be treated as data by 
IEBCOMPR. For a discussion of this option, refer to ‘“‘Processing User Labels as 
Data” in ‘“‘Appendix E: Processing User Labels.” 


The format of the LABELS statement is: 


J 


where: 


DATA= 
specifies whether user labels are to be treated as data. The values that can be 
coded are: 


YES 
specifies that any user labels that are not rejected by a user’s label 
processing routine are to be treated as data. Processing of labels as data 
stops in compliance with standard return codes. If no value is entered, YES 
is assumed. 


NO 
specifies that user labels are not to be treated as data. 


ALL 
specifies that user labels are to be treated as data regardless of any return 
code. A return code of 16 causes IEBCOMPR to complete processing of the 
remainder of the group of user labels and to terminate the job step. 


ONLY 
specifies that only user header labels are to be treated as data. User header 
labels are processed as data regardless of any return code. The job 
terminates upon return from the OPEN routine. 


If more than one valid LABELS statement is included, all but the last LABELS 
statement are ignored. 


IEBCOMPR Examples 


The examples that follow illustrate some of the uses of IEBCOMPR. Table 8 can 
be used as a quick reference guide to IEBCOMPR examples. The numbers in the 
“Example” column point to examples that follow. 


Table 8. IEBCOMPR Example Directory 


Data Set 

Operation Organization Devices Comments Example 
COMPARE Sequential 9-track tape No user routines. Blocked input. I 
COMPARE Sequential 7-track tape No user routines. Blocked input. 2 
COMPARE Sequential 7-track and User routines. Blocked input. 

9-track tape Different density tapes. 3 
COMPARE Sequential Card Reader, No user routines. Blocked input. 

9-track tape 4 
COMPARE Partitioned 2314 Disk No user routines. Blocked input. 5 
COPY (using Sequential 9-track tape No user routines. Blocked input. 
IEBCOPY) Two job steps; data sets are 
and COMPARE passed to second job step. 6 
COPY (using — Partitioned 2314 Disk User routine. Blocked input. 
IEBCOPY) and Two job steps; data sets are 
COMPARE passed to second job step. 7 


IEBCOMPR Example 1 


In this example, two sequential data sets that reside on 9-track tape 
volumes are to be compared. 
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IEBCOMPR Example 2 
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The example follows: 


//TAPETAPE JOB 09#660,SMITH 

7 7 EXEC PGM=IEBCOMPR 

//SYSPRINT DD SYSOUT=A 

J//SYSUT1 DD UNIT=2400, LABEL=( ,NL}, 

// DCB=( RECFM=FB,LRECL=80, BLKSIZE=2000 ), 

// DISP=( OLD, KEEP ), VOLUME=SER=001234 

//SYSUT2 DD UNIT=2400, LABEL=( ,NL), DISP=(OLD,KEEP), 
// DCB=( RECFM=FB,LRECL=80,BLKSIZE=1040 ), 

// VOLUME=SER=001235 

J//SYSIN DD DUMMY 

/* 

Because no user routines are to be used and the input data sets have a sequential 
organization, utility control statements are not used. 


The control statements are discussed below: 


¢ SYSUT1 DD defines an input data set, which resides on an unlabeled, 9-track 
tape volume. The blocked data set was originally written at a density of 800 
bits per inch. 


¢ SYSUT2 DD defines an input data set, which resides on an unlabeled, 9-track 
tape volume. The blocked data set was originally written at a density of 800 
bits per inch. 


e SYSIN DD defines a dummy data set. 


In this example, two sequential data sets that reside on 7-track tape volumes are 
to be compared. 


The example follows: 


//TAPETAPE JOB 09#660,SMITH 
J} EXEC PGM=IEBCOMPR 
//SYSPRINT DD  SYSOUT=A 
//SYSUT1 DD  DSNAME=SET1,LABEL=(2,SUL),DISP=(OLD,KEEP), 
// VOL=SER=001234,DCB=( DEN=2,RECFM=FB,LRECL=80, 
// BLKSIZE=2000,TRTCH=C ) ,UNIT=2400-2 
//SYSUT2 DD  DSNAME=SET1,LABEL=( ,SUL),DISP=(OLD,KEEP), 
// JOL=SER=001235,DCB=( DEN=2,RECFM=FB, LRECL=80, 
// BLKSIZE=2000, TRTCH=C ), UNIT=2400-2 
//SYSIN DD * 

COMPARE  TYPORG=PS 

LABELS DATA=ONLY 

/* 


The control statements are discussed below: 


e SYSUTI DD defines an input data set, which resides on a labeled, 7-track 
tape volume. The blocked data set was originally written at a density of 800 
bits per inch with the data converter on. 


e SYSUT2 DD defines an input data set, which is the first or only data set on a 
labeled, 7-track tape volume. The blocked data set was originally written at a 
density of 800 bits per inch with the data converter on. 


e SYSIN DD defines the control data set, which follows in the input stream. 
e COMPARE specifies that the input data sets are sequentially organized. 


e LABELS specifies that only user header labels are to be compared. 
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IEBCOMPR Example 4 


In this example, two sequential data sets written at different densities on 
different device types are to be compared. 


The example follows: 


//TAPETAPE JOB 09#660,SMITH 
{7 EXEC PGM=IEBCOMPR 
//SYSPRINT DD SYSOUT=A 
ffa(SUT| DD DSNAME=SET1, LABEL=( ,SUL),DISP=(OLD,KEEP), 
// VOL=SER=00 1234 ,DCB=( DEN=1,RECFM=FB, LRECL=80, 
// BLKSIZE=320,TRTCHE=C ),UNIT=2400-2 
VPoVSUiZ DD DSNAME=SET2,LABEL=( ,SUL),DISP=(OLD,KEEP), 
// DCB=( RECFM=FB, LRECL=80, BLKSIZE=640 ), 
// NOLUME=SER=001235,UNIT=2400 
ff SYS DD * 

COMPARE TY PORG=PS 

EXITS INHDR=HDRS, INTLR=TLRS 
LABELS DATA=NO 


/* 
The control statements are discussed below: 


e SYSUT1 DD defines an input data set, which is the first or only data set on a 
labeled, 7-track tape volume. The blocked data set was originally written at a 
density of 556 bits per inch with the data converter on. 


e SYSUT2 DD defines an input data set, which is the first or only data set on a 
labeled, 9-track tape volume. The blocked data set was originally written at a 
density of 800 bits per inch. 


e SYSIN DD defines the control data set, which follows in the input stream. 
e COMPARE specifies that the input data sets are sequentially organized. 


e EXITS identifies the names of routines to be used to process user input header 
labels and trailer labels. 


¢ LABELS specifies that the user input header and trailer labels are not to be 
compared. 


In this example, two sequential data sets (card input and tape input) are to be 
compared. 


The example follows: 


//CARDTAPE JOB 09#660,SMITH 


7 EXEC PGM=IEBCOMPR 
J /SYSPRINT DD SYSOUT=A 
~7SY.SIN DD DUMMY 


ZF SX SUT 2] DD UNIT=2400, VOLUME=SER=001234,LABEL=(,NL), 
// DCB=( RECFM=FB,LRECL=80,BLKSIZE=2000 ), 

// DISP=COLD,KEEP ) 

J7StSuTt DD DATA 


(input card data set) 
/* 
The control statements are discussed below: 


e SYSIN DD defines a dummy control data set. Because no user routines are 
provided and the input data sets are sequential, utility control statements are 
not used. 


e SYSUT2 DD defines an input data set, which resides on an unlabeled, 9-track 
tape volume. The blocked data set was originally written at a density of 800 
bits per inch. 
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IEBCOMPR Example 5 


IEBCOMPR Example 6 
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¢ SYSUT1 DD defines an input data set (card input). 


In this example, two partitioned data sets are to be compared. 


The example follows: 


//DISKDISK JOB 09#660,SMITH 


fy EXEC PGM=IEBCOMPR 

//SYSPRINT DD  SYSOUT=A 

//SYSUT1 DD DSNAME=PDSSET,UNIT=2314,DISP=(OLD,KEEP), 
// DCB=( RECFM=FB, LRECL=80,BLKSIZE=2000), 

// JOLUME=SER=111112 


J fot oT? DD DSNAME=PDSSET,UNIT=2314,DISP=(OLD,KEEP), 
// DCB=( RECFM=FB, LRECL=80, BLKSIZE=2000 ), 
77 NOLUME=SER=1 711-13 
/ /SYSIN DD * 
COMPARE TY PORG=PO 
/* 


The control statements are discussed below: 


¢ SYSUT1 DD defines an input partitioned data set. The blocked data set 
resides on a 2314 volume. 


¢ SYSUT2 DD defines an input partitioned data set. The blocked data set 
resides on a 2314 volume. 


e SYSIN DD defines the control data set, which follows in the input stream. The 
data set consists of one utility control statement. 


In this example, a sequential data set is to be copied and compared in two job 
steps. 


The example follows: 


//TAPETAPE JOB 09#660,SMITH 

//STEPA EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

FISISUY DD DSN=COPYSET, UNIT=2400,DISP=(OLD,PASS), 
// DCB=( RECFM=FB,LRECL=80,BLKSIZE=640), 

// UABEL=( ,SL), VOLUME=SER=001234 

//SYSUT2 DD DSNAME=COPYSET,DISP=(,PASS),LABEL=(,SL), 
// DCB=( RECFM=FB, LRECL=80, BLKSIZE=640), 

// VOLUME=SER=001235,UNIT=2400 


f/oLo TN DD DUMMY 

/* 

J 7STEPB EXEC PGM=IEBCOMPR 

i /SISPRINT .DD SYSOUT=A 

Fe ow oo Oi DD. DSNAME=*.STEPA.SYSUT],DISP=(OLD;KERP’) 
J FEY SEZ DD DSNAME=*.STEPA.SYSUT2,DISP=( OLD, KEEP ) 
7 SYSLIN DD DUMMY 

/* 


The first job step copies the data set and passes the original and copied data sets 
to the second job step. The second job step compares the two data sets. 


The control statements for the IERBCOMPR job step are discussed below: 


e SYSUT1 DD defines an input data set passed from the preceding job step. 
The data set resides on a labeled, 9-track tape volume. The blocked data set 
was originally written at a density of 800 bits per inch. 
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e SYSUT2 DD defines an input data set passed from the preceding job step. 
The data set, which was created in the preceding job step, resides on a 
labeled, 9-track tape volume. The blocked data set was originally written at a 
density of 800 bits per inch. 


e SYSIN DD defines a dummy control data set. Because the input is sequential 
and no user exits are provided, no utility control statements are required. 


In this example, a partitioned data set is to be copied and compared in two job 
steps. 


The example follows: 


//DISKDISK JOB 09#660,SMITH 

//STEPA EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=OLDSET,UNIT=2314,DISP=(OLD, PASS), 
// VOLUME=SER=111112,DCB=( RECFM=FB, LRECL=80, 

// BLKSIZE=640 ) 

//SYSUT2 DD DSNAME=NEWMEMS , UNIT=2314,DISP=(,PASS), 
// VOLUME=SER=111113,SPACE=(TRK,(5,5,5)), 

// DCB=( RECFM=FB, LRECL=80, BLKSIZE=640 ) 


JJ SEXSUT3 DD 
//SYSUT4 DD 


JIS TSIN DD 
COPY 
SELECT 
/* 
JJ STEPB 


//SYSPRINT DD 
J7SYSUT) DD 
TJSLSU ie DD 
JF SYSIN DD 
COMPARE 

Bans 


UNIT=2314,SPACE=( TRK,(1)) 
UNIT=2314,SPACE=(TRK,(1)) 
* 

OUTDD=SYSUT2, INDD=SYSUT1 
MEMBER=(A,B,D,E,F) 


EXEC PGM=IEBCOMPR 


SYSOUT=A 

DSNAME=OLDSET , DISP=( OLD, KEEP ) 

DSNAME=NEWMEMS , DISP=( OLD, KEEP ) 
* 

TY PORG=PO 

ERROR=SEEERROR 


/* 
The first job step copies the data set and passes the original and copied data sets 
to the second job step. The second job step compares the two data sets. 


The control statements for the IEBCOMPR job step are discussed below: 


¢ SYSUT1 DD defines a blocked input data set that is passed from the 
preceding job step. The data set resides on a 2314 volume. 


¢ SYSUT2 DD defines a blocked input data set that is passed from the 
preceding job step. The data set resides on a 2314 volume. 


e SYSIN DD defines the control data set, which contains a COMPARE 
statement and an EXITS statement. 


e COMPARE specifies partitioned organization. 
¢ EXITS specifies that a user routine, SEEERROR, is to be used. 


Because the input data set names are not identical, the data sets can be retrieved 
by their data set names. 
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IEBCOPY Program 


IEBCOPY is a data set utility used to copy one or more partitioned data sets or 
to merge partitioned data sets. (See “Introduction” for general data set utility 
information.) One partitioned data set can be unloaded to a sequential data set. 
The sequential data set created by an unload operation can be loaded to any 
direct access device. Specified members of a partitioned or unloaded data set can 
be selected for, or excluded from, a copy, unload, or load process. 


IEBCOPY can be used to: 
e Create a backup copy. 
tl e Copy one or more data sets per copy operation. 
e Copy one partitioned data set to a sequential data set (unload). 


e Copy one or more data sets created by an unload operation to any direct 
access device (load). 


¢ Select members from a data set to be copied, unloaded, or loaded. 

¢ Replace identically named members on data sets (except when unloading). 
e Replace selected data set members. 

e Rename selected members. 


e Exclude members from a data set to be copied, unloaded, or loaded. 


e Compress partitioned data sets in place (except when the data set is an 
unloaded data set). 


e Merge data sets (except when unloading). 


e Recreate a data set that has exhausted its primary, secondary, or directory 
space allocation. 


In addition, IEBCOPY automatically lists the number of unused directory blocks 
and the number of unused tracks available for member records in the output 
partitioned data set. If LIST=NO is coded (see “COPY Statement’’), the names 
of copied, unloaded, or loaded members listed by the input data set are 
suppressed. 


When copying members that have aliases, the following should be noted: 


e When the main member and its aliases are copied, they exist on the output 
partitioned data set in the same relationship they had on the input partitioned 
data set. 


e When one alias is copied without its main member, it becomes a main 
member. 


e When two or more aliases are copied, unloaded, or loaded without the main 
member, the lowest alias (in alphameric collating sequence) becomes the main 
member; any remaining aliases become aliases of the new main member. 
Note that if an old main member name is present in an alias entry, it remains 
there. 
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Creating a Backup Copy 


Copying Data Sets 


The rules for replacing or renaming members apply to both aliases and members; 
no distinction is made between them. Note, however, that the replace option 
does not apply to an unload operation. 


At the completion or termination of the program, the highest return code 
encountered within the program is passed to the calling program. 


IEBCOPY can be used to create a backup copy of a data set by 
unloading—copying in sequential organization—a data set. A partitioned data set 
can be unloaded, totally or in part, to any tape volume or direct access device 
supported by BSAM. A data set is unloaded when physical sequential 
organization space allocation is specified for the output data set on a direct 
access device or when the output data set is a tape volume. To unload more than 
One partitioned data set to the same volume in one execution of IEBCOPY, 
multiple copy operations must be used and multiple sequential data sets must be 
allocated on the same volume. 


A data set with a physical sequential organization resulting from an unload 
operation can be unloaded a second time. 


IEBCOPY can be used to copy a partitioned data set, totally or in part, from one 
direct access volume to another. In addition, a data set can be copied to its own 
volume, provided its data set name is changed. If the data set name is not 
changed, the data set is compressed in place. 


Note that copied members are not reordered. Members are copied in the order in 
which they exist on the original data set. If the members are to be reordered, 
IEHMOVE can be used for the copy operation (see “IEHMOVE Program’’). 


Copying an Unloaded Data Set to Direct Access 


Data sets created by an unload operation can be loaded to any direct access 
device. The output partitioned data set will have the same characteristics as it 
had before the operation. A load operation is requested by specifying a 
sequential input data set unloaded by IEBCOPY. 


Copying or Loading Data Sets 


Data sets can be copied or loaded, totally or in part, from one or more direct 
access volumes or tape volumes to a single direct access volume. To copy or load 
more than one input partitioned data set, specify more than one input data set 
(see ““COPY Statement’’ below). The input data sets are copied or loaded in the 
order in which they are specified. 


Selecting Members to be Copied, Unloaded, or Loaded 
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Members can be selected from one or more input data sets. Selected members 
are copied, unloaded, or loaded from the input data sets specified on the INDD 
statement preceding a SELECT statement. (See ““COPY Statement”’ and 
“SELECT Statement” in this chapter.) 


Selected members are searched for in a low-to-high (a-to-z) collating sequence, 
regardless of the order in which they are specified; however, they are copied in 
the same physical sequence in which they appear on the input partitioned data 
set. 


When selecting members from an input data set, remember that once a member 
is found it is not searched for on any subsequent input data set. Similarly, when 
all of the selected members are found, the copy or load step is terminated 
although all of the input data sets may not have been searched. For example, if 
members A and B are specified and A is found on the first of three input data 
sets, it is not searched for again; if B is found on the second input data set, the 
copy or load operation is successfully terminated after the second input data set 
has been processed, although both A and B may also exist on the third input 
data set. 


However, if the first member name is not found on the first input data set, the 
second selected member is searched for; if it is not found, the third is searched 
for, and so on. This process continues until there are no more members to be 
searched for in this input data set. All the members that were found on the input 
data set are then processed for copying, unloading, or loading to the output data 
set. This process is repeated for the second input data set (except that the 
members that were found on the first input data set are not searched for again). 


Note: Only one data set can be processed if an unload operation is to be 
performed. 


Replacing Identically Named Members 


In many copy and load operations, the output partitioned data set may contain 
members that have names identical to the names of the input partitioned data set 
members to be copied or loaded. When this occurs, the user may specify that the 
identically named members are to be copied from the input partitioned data set 
to replace existing members. 


The replace option allows an input member to override an existing member on 
the output partitioned data set with the same name. The pointer in the output 
partitioned data set directory is changed to point to the copied or loaded 
member. 


If the replace option is not specified, input members are not copied when they 
have the same name as a member on the output partitioned data set. 


The replace option can be specified on the data set or member level. The level is 
specified on a utility control statement. 


When replace is specified on the data set level (specified on a COPY or INDD 
statement), the input data is processed as follows: 


e Ina full copy or load process, all members on an input partitioned data set are 
copied to an output partitioned data set; members whose names already exist 
on the output partitioned data set are replaced by the members copied or 
loaded from the input partitioned data set. 


¢« Ina selective copy or load process, all selected members on an input 
partitioned data set are copied or loaded to an output partitioned data set; all 
selected members found are copied or loaded and members whose names 
already exist on the output partitioned data set are replaced by the found 
members copied or loaded from the input partitioned data set. 


e In an exclusive copy process, all non-excluded members on input partitioned 
data sets are copied or loaded to an output partitioned data set; non-excluded 
input members whose names already exist on the output paititioned data set 
replace those duplicate-named members on the output partitioned data set. 


When replace is specified on the member level (specified on a SELECT 
statement), only selected members for which replace is specified are copied or 
loaded, and identically named members on the output partitioned data set are 
replaced. 
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There are differences between full, selective, and exclusive copy or load 
processing. These differences should be remembered when specifying the replace 
option and all of the output data sets contain member names common to some or 
all of the input partitioned data sets being copied or loaded. These differences 


are ) 
¢ When a full copy or load is performed, the output partitioned data set contains 
the replacing members that were on the last input partitioned data set copied. 


e When a selective copy or load is performed, the output partitioned data set 
contains the selected replacing members which were found on the earliest 
input partitioned data set searched. Once a selected member is found, it is not 
searched for again; therefore, once found, a selected member is copied or 
loaded. If the same member exists on another input partitioned data set it is 
not searched for, and hence, not copied or loaded. 


e When an exclusive copy or load is performed, the output partitioned data set 
contains the non-excluded replacing members that were on the last input 
partitioned data set copied or loaded. 


Replacing Selected Members 


The user may specify the replace option on either the data set or the member 
level when members are being selected for copying or loading. 


If the replace option is specified on the data set level, all selected members found 
on the designated input data sets replace identically named members on the 
output partitioned data set. This is limited by the fact that once a selected 
member is found it is not searched for again. 


If the replace option is specified on the member level, the specified members on 

the input data set replace identically named members on the output partitioned 

data set. Once a member is found it is not searched for again. (See “‘Replacing ; 
Identically Named Members” earlier in this chapter.) Za 


Renaming Selected Members 


Selected members on input data sets can be copied and renamed on the output 
data set. However, in the case of a copy or load operation, if the new name is 
identical to a member name on the output data set, the input member is not 
copied or loaded unless the replace option is also specified. See ““SELECT 
Statement” below for information on renaming selected members. 


Note: Renaming is not physically done to the input data set directory entry. The 
output data set directory, however, will contain the new name. 


Excluding Members from a Copy Operation 


60 OS/VS Utilities 


Members from one or more input data sets can be excluded from a copy, unload, 
or load operation. The excluded member is searched for on every input data set 
in the copy, unload, or load operation and is always omitted. Members are 
excluded from the input data sets named on an INDD statement that precedes 
the EXCLUDE statement. (See ““COPY Statement”? and “EXCLUDE 
Statement” in this chapter.) 


The replace option can be specified on the data set level in an exclusive copy or 
load, in which case, non-excluded members on the input data set replace 
identically named members on the output data set. See “Replacing Identically 
Named Members” earlier in this chapter for more information on the replace 
option. 


C 


Compressing a Data Set 


Merging Data Sets 


Re-creating a Data Set 


Input and Output 


A compressed data set is one that does not contain embedded, unused space. 
After copying or loading one or more input partitioned data sets to a new 
output partitioned data set (by means of a selective, exclusive, or full copy or 
load that does not involve replacing members), the output partitioned data set 
contains no embedded, unused space. 


To make unused space available, either the entire data set must be scratched or it 
must be compressed in place. A compressed version can be created by specifying 
the same data set for both the input and the output parameters in a full copy 
step. A backup copy of the partitioned data set to be compressed in place should 
be kept until successful completion of an in-place compression is indicated (by an 
end-of-job message and a return code of 00). 


An in-place compression does not release extents assigned to the data set. 


Note: When the same ddname is specified for the INDD and OUTDD keywords 
(see ““COPY Statement” below) and the DD statement specifies a block size 
different from the block size specified in the DSCB, the DSCB block size is 
overridden; however, no physical reblocking or deblocking is performed by 
IEBCOPY. 


A merged data set is one to which an additional member is copied or loaded. It is 
created by copying or loading the additional members to an existing output 
partitioned data set; the merge operation—the ordering of the output partitioned 
data set’s directory—is automatically performed by IEBCOPY. 


Note: If there is a question about whether or not enough directory blocks are 
allocated to the output partitioned data set to which an input data set is being 
merged, the output partitioned data set should be re-created prior to the merge 
operation. 


A data set can be re-created by copying or loading it and allocating a larger 
amount of space than was allocated for the original data set. This application of 
IEBCOPY is especially useful if insufficient directory space was allocated to a 
data set. Space cannot be allocated in this manner for an existing partitioned data 
set into which members are being merged. 


IEBCOPY uses the following input: 


e« An input data set, which contains the members to be copied, loaded, or 
merged into a partitioned data set or unloaded to a sequential data set. 


e A control data set, which contains utility control statements. The control data 
set is required if members are to be selected for or excluded from a copy, 
unload, load, or merge operation. 


If the control data set is null, a full copy is attempted from the input partitioned 
data set to the output partitioned data set. In this case, SYSUT1 and SYSUT2 
are required ddnames for the input partitioned data set and output partitioned 
data set, described under ‘‘Job Control Statements” below. 
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IEBCOPY produces the following output: 


e An output data set, which contains the copied, merged, unloaded, or loaded 
data. The output data set is either a new data set (from a copy, load, or 
unload) or an old data set (from a merge, compress-in-place, copy, or load). 


¢ A message data set, which contains informational messages (for example, the 
names of copied, unloaded, or loaded members) and error messages, if 
applicable. 


e Spill data sets, which are temporary data sets used to provide space when not 
enough main storage is available for the input and/or output partitioned data 
set directories. These data sets are opened only when needed. 


Note: Refer to OS/VS1 Storage Estimates, GC24-5094, or OS/VS2 Storage 
Estimates , GC28-0604, to determine when spill data sets are required; see 
“Space Allocation” below for a description of how to determine the amount of 
space to allocate. 


The following direct access devices may be used for input, output, and utility 
data sets: 


e 2314 Direct Access Storage Facility 

e 3330 Disk Storage 

e 2305 Fixed Head Storage 

Any combination of these devices is acceptable to IEBCOPY. 

The following magnetic tape devices may be used for unloaded data sets: 
e 2400 series 

e 3410 series 

e 3420 series 


Note: The sequentially organized output from an unload operation or the 
sequentially organized input for a load operation may also reside on a direct 
access device. 


IEBCOPY produces a return code to indicate the results of program execution. 
The return codes and their meanings are: 


e 00, which indicates successful completion. 
e 04, which indicates a condition from which recovery may be possible. 


e O08, which indicates an unrecoverable error. The job step is terminated. 


Control 


IEBCOPY is controlled by job control statements and utility control statements. 


Job Control Statements 
Table 9 shows the job control statements necessary for using IEBCOPY. 
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Table 9. IEBCOPY Job Control Statements 


Statement Use 
JOB Initiates the job. 
EXEC Specifies the program name (PGM=IEBCOPY) or, if the job control 


statements reside in the procedure library, the procedure name. This 
statement can include optional PARM information to define the size of the 
buffer to be used: see “-PARM Information on the EXEC Statement” below. 


SYSPRINT DD Defines the sequential message data set used for listing statements and 
messages. This data set can be written to a system output device, a tape 
volume, or a direct access volume. 


INPUT DD Defines an input partitioned data set. INPUT DD statements can describe 
partitioned data sets on direct access devices or sequential data sets, created 
as a result of unload operations, on tape or direct access devices. The data set 
can be defined by a data set name, as a cataloged data set, or as a data set 
passed from a previous job step. 


OUTPUT DD _ Defines an output partitioned data set. OUTPUT DD statements can describe 
partitioned data sets on direct access devices or sequential data sets, created 
as a result of unload operations, on tape or direct access devices. 


SYSUT3 DD Defines a spill data set on a direct access device. SYSUT3 is used when there 
is NO Space in main storage for some or all of the current input partitioned 
data set's directory entries. SYSUT3 may also be used when not enough space 
is available in main storage for retaining information during table sorting. 


SYSUT4 DD Defines a spill data set on a direct access device. SYSUT4 is used when there 
is nO space in main storage for the current output partitioned data set's 
merged directory and the output partitioned data set is not new. 


SYSIN DD Defines the control data set. The control data set normally resides in the 
input stream; however, it can reside on a system input device, a tape volume, 
or a direct access volume. 


Fixed or variable records can be reblocked. Reblocking or deblocking is done if 
the block size of the input partitioned data set is not equal to the block size of 
the output partitioned data set. Reblocking or deblocking cannot be done if 
either the input or the output data set has undefined format records, keyed 
records, track overflow records, note lists, or user TTRN’s, or if 
compress-in-place is specified. 


An unloaded partitioned data set will have a variable spanned record format. 
When an unloaded data set is subsequently loaded, the output data set will have 
the same characteristics it had before the unload operation, unless specified 
differently by the user. 


For unload and load operations, requests are handled in the same way as for a 
copy operation. 


Table 10 shows how input record formats can be changed. In addition, any 
record format can be changed to the undefined format (in terms of its 
description in the DSCB). 


Table 10. Changing Input Record Format Using IEBCOPY 


Input Output 

Fixed Fixed Blocked 
Fixed Blocked Fixed 

Variable Variable Blocked 


Variable Blocked Variable 


System data sets should not be compressed in place unless the subject partitioned 
data set is made non-shareable . 


Refer to OS/VS Data Management Services Guide, GC26-3783, for 
information on estimating space allocations. 
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Restrictions 


Refer to OS/VSI Storage Estimates, GC24-5094, or OS/VS2_ Storage 

Estimates , GC28-0604, to determine when spill data sets are required; see 

“Space Allocation” below for a description of how to determine the amount of 

space to allocate. 

e SYSPRINT and SYSIN are mandatory DD statements. The block size for the 
SYSPRINT data set must be a multiple of 121. The block size for the SYSIN 


data set must be a multiple of 80. Any blocking factor may be specified for 
these data sets, with a maximum allowable block size of 32,767 bytes. 


e The SYSPRINT DD statement must define a data set with fixed-blocked or 
fixed records. 


e INPUT DD and OUTPUT DD statements are required. There must be one 
INPUT DD statement for each unique data set used for input and one 
OUTPUT DD statement for each unique data set used for output in the job 
step. 


e Input data sets cannot be concatenated. 


e The SYSIN DD statement must define a data set with fixed-block or fixed 
records. 


PARM Information on the EXEC Statement 


Space Allocation 
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The EXEC statement for IEBCOPY can contain PARM information that is used 
to define the number of bytes used as a buffer. The PARM parameter can be 
coded: 


PARM='‘SIZE=nnnnnnnnolK]’ 


The nnnnnnnn can be replaced by one to eight digits. The K causes the 
nnnnnnnn to be multiplied by 1024. 2 


If PARM is not specified, is invalidly specified, or a value below the minimum 
buffer size is specified, IEBCOPY defaults to the minimum buffer size, which is 
twice the maximum of the input or output block sizes or the input or output 
track capacities. 


The maximum buffer size that can be specified is equal to the remaining storage 
available in the partition when the buffer is allocated. If the value specified in 
PARM exceeds this maximum, IEBCOPY defaults to the maximum. 


Sometimes it is necessary to allocate space on spill data sets (SYSUT3 and 
SYSUT4). The space to be allocated for SYSUT3 depends on the number of 
members to be copied or loaded. The space to be allocated for SYSUT4 depends 
on the number of directory blocks to be written to the output data set. 


To conserve space on the direct access volume, an initial quantity and a 
secondary quantity for space allocation may be used, as shown in the following 
SPACE parameter: 


SPACE=(c,(x,y)) 


The c value should be a block length of 80 for SYSUT3 and of 256 for 
SYSUT4. The x value is the number of blocks in the primary allocation, and the 
y value is the number of blocks in a secondary allocation. 


For SYSUT3, x + 15y must be equal to or greater than the number of entries in 
the largest input partitioned data set in the copy operation, multiplied by 1.05. 


L 


For SYSUT4, x + 15y must be equal to or greater than the number of blocks 
allocated to the largest output partitioned data set directory in the IEBCOPY job 
step. 


For example, if there are 700 members on the largest input partitioned data set, 
space could be allocated for SYSUT3 as follows: 
SPACE=(80,(25,45)) 


However, the total amount of space required for SYSUT3 in the worst case is 
used only if needed. If space is allocated in this manner for SYSUT4, the user 
must specify in his SYSUT4 DD statement: 


DCB=(KEYLEN=8) 


Note that IEBCOPY ignores all other DCB information specified for SYSUT3 
and/or SYSUT4. Multi volume SYSUT3 and SYSUT4 data sets are not 
supported. 


Utility Control Statements 


COPY Statement 


IEBCOPY is controlled by the following utility control statements: 
e COPY statement, which indicates the beginning of a COPY operation. 


e SELECT statement, which specifies which members in the input data set are 
to be copied. 


e EXCLUDE statement, which specifies members in the input data set to be 
excluded from the copy step. 


In addition, when INDD, a COPY statement parameter, appears on a card other 
than the COPY statement, it is referred to as an INDD statement; it can function 
as a control statement in this context. 


Utility control statements may be continued on subsequent cards provided that 
all the data is contained in columns 2 through 71. Control statement operation 
and keyword parameters can be abbreviated to their initial letters; COPY, INDD, 
OUTDD, and LIST can be abbreviated to C, I, O, and L. 


The COPY Statement is required to initiate one or more IEBCOPY copy, 
unload, or load operations. Any number of operations can follow a single COPY 
Statement; any number of COPY statements can appear within a single job step. 


Note: IEBCOPY copy, unload, and load operations are specified by a 
combination of job control language and utility control statements. For a full 
discussion of how these operations are specified, see ““IEBCOPY Examples” later 
in this chapter. 


A COPY statement must precede a SELECT or EXCLUDE statement when 
members are selected for or excluded from a copy, unload, or load step. In 
addition, if an input ddname is specified on a separate INDD statement, it must 
follow the COPY statement and precede the SELECT or EXCLUDE statement 
to which it applies. If one or more INDD statements are immediately followed by 
the /* card or another COPY statement, a full copy, unload, or load is invoked 
onto the most recent output partitioned data set previously specified. 
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IEBCOPY uses a copy operation/copy step concept.’ A copy operation starts 
with a COPY statement and continues until either another COPY statement or 
the end of the control data set is found. Within each copy operation, one or 
more copy steps are present. Any INDD statement directly following a SELECT 
or EXCLUDE statement marks the beginning of the next copy step and the end 
of the preceding copy step within the copy operation. If such an INDD statement 
cannot be found in the copy operation, then the copy operation consists of only 
one copy step. 


Figure 5 shows the copy operation/copy step concept. Two copy operations are 
shown in the figure: the first begins with the statement containing the name 
COPOPERI, and the second begins with the statement containing the name 
COPOPER2. 


There are two copy steps within the first copy operation shown in Figure 5: the 
first begins with the COPY statement and continues through the two SELECT 
Statements; the second begins with the first INDD statement following the two 
SELECT statements and continues through the EXCLUDE statement preceding 
the second COPY statement. There are two copy steps within the second copy 
operation: the first begins with the COPY statement and continues through the 
SELECT statement; the second begins with the INDD statement immediately 
following the SELECT statement and ends with the same /* (delimiter) 
Statement that ended the copy operation. 
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Copy INDD=HH 
Operation EXCLUDE MEMBER=MEMD,MEMH 
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Figure 5. Multiple Copy Operations Within a Job Step 


The format of the COPY statement is: 
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where: 
OUTDD= ddname 
specifies the name of the output partitioned data set. One ddname is required 
for each copy, unload, or load operation; the ddname used must be specified 
on a DD statement. 


' The same applies to an unload or load operation or step. 


» 


INDD= 
specifies the names of the input partitioned data sets. INDD may, optionally, 
be placed on a separate card following a COPY statement containing the 
OUTDD parameter, another INDD statement, a SELECT statement, or an 
EXCLUDE statement. These values can be coded: 


ddname 
specifies the ddname, which is specified on a DD statement, of an input 
data set. For an unload operation, only one ddname may be specified per 
COPY statement. If more than one ddname is specified in the case of a 
copy or load operation, the input data sets are processed in the same 
sequence as the ddnames are specified. 


specifies that all members to be copied or loaded from this input data set 
are to replace any identically named members on the output partitioned 
data set. (In addition, members whose names are not on the output 
partitioned data set are copied or loaded as usual.) When this option is 
specified with the INDD parameter, it does not have to appear with the 
MEMBER parameter (discussed in “SELECT Statement” in this chapter) 
in a selective copy operation. When this option is specified, the ddname and 
the R parameter must be enclosed in a set of parentheses; if it is specified 
with the first ddname in INDD, the entire field, exclusive of the INDD 
parameter, must be enclosed in a second set of parentheses. 


LIST=NO 
specifies that the names of copied members are not to be listed on SYSPRINT 
atthe end of each input data set. If LIST is not coded, the names of copied , 
members are listed. Eo 


Note: The control statement operation and keyword parameters can be 
abbreviated to their initial letters; for example, COPY can be abbreviated to C 
and OUTDD can be abbreviated to O. 


Only one INDD and one OUTDD keyword may be placed on a single card. 
OUTDD must appear on the COPY statement. When INDD appears on a 
separate card, no other operands may be specified on that card. 


INDD may appear on a separate card; if this option is selected, INDD is not 
preceded by a comma. 


If there are no keywords on the COPY card, compatibility with the previous 
version is implied. In this case, comments may not be placed on this card. 


If more than one ddname is specified, the input partitioned data sets are 
processed in the same sequence as that in which the ddnames are specified. 


A full copy, unload, or load is invoked only by specifying different input and 
output ddnames; that is, by omitting the SELECT or EXCLUDE statement from 
the copy step. 


The compress-in-place function is valid for partitioned data sets. 
Compress-in-place is normally invoked by specifying the same ddname (with the 
same dsname and volume serial number specified on the DD statement) for both 
the OUTDD and INDD parameters of a COPY statement. If multiple entries are 
made on the INDD statement, a compress in place will occur if one of the input 
ddnames is the same as the ddname specified by the OUTDD parameter of the 
COPY statement, provided that SELECT or EXCLUDE is not specified. 


The compress-in-place function cannot be performed for the following: 


e An unloaded data set. 
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e A data set with track overflow records. 
e A data set with keyed records. 


e A data set for which reblocking is specified in the DCB parameter. 


e An unmovable data set. ) 


When a compression is invoked by specifying the same ddname for the INDD 
and OUTDD parameters, and the DD statement specifies a block size that differs 
from the block size specified in the DSCB, the DSCB block size is overridden; 
however, no physical reblocking or deblocking is done by IEBCOPY. 


The SELECT statement specifies members to be selected from input data sets to 
be copied, loaded, or unloaded to an output data set. This statement is also used 
to rename and/or replace selected members on the output data set. More than 
one SELECT statement may be used in succession, in which case the second and 
subsequent statements are treated as a continuation of the first. 


The SELECT statement must follow either a COPY statement that includes an 
INDD parameter or one or more INDD statements. A SELECT statement cannot 
appear with an EXCLUDE statement in the same copy, unload, or load step. 


When a selected member is found on an input data set, it is not searched for 
again, regardless of whether it the member is copied, unloaded, or loaded. A 
selected member will not replace an identically named member on the output 
partitioned data set unless the replace option is specified on either the data set or 
member level. (For a description of replacing identically named members see 
“Replacing Identically Named Data Set Members,” and “‘Replacing Selected 
Members” in this chapter.) In addition, a renamed member will not replace a 
member on the output partitioned data set that has the same new name as the 
renamed member, unless the replace option is specified. J 


The format of the SELECT statement is: 


where: 


MEMBER= 
specifies the members to be selected from the input data set. The values that 
can be coded are: 


name 
specifies the name of a member that is to be selected in a copy step. Each 
member name specified within one copy step must be unique; that is, 
duplicate names cannot be specified as either old names, or new names, or 
both, under any circumstances. 


newname 
specifies a new name for a selected member. The member is copied, 
unloaded, or loaded to the output partitioned data set using its new name. 
If the name already appears on the output partitioned data set, the member 
is not copied unless replacement is also specified. 


EXCLUDE Statement 
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R 
specifies that the input member is to replace any identically named member 
that exists on the output partitioned data set. The replace option is not valid 
for an unload operation. 


Note: The control statement operation and keyword parameter can be 
abbreviated to their initial letters; SELECT can be abbreviated to S and 
MEMBER can be abbreviated to M. 


To rename a member, the old member name is specified in the SELECT 
statement, followed by the new name and, optionally, the R parameter. When 
this option is specified, the old member name and new member name must be 
enclosed in a set of parentheses; if it is specified for the first name in the 
MEMBER field, the entire field, exclusive of the MEMBER keyword, must be 
enclosed in a second set of parentheses. 


The EXCLUDE statement specifies members to be excluded from the copy, 
unload, or load step. Unlike the selective copy, unload, or load, an exclusive 
copy, unload, or load causes all members specified on each EXCLUDE statement 
to be omitted from the operation. 


More than one EXCLUDE statement may be used in succession, in which case 
the second and subsequent statements are treated as a continuation of the first. 
The EXCLUDE statement must follow either a COPY statement that includes an 
INDD parameter or one or more INDD statements. An EXCLUDE statement 
cannot appear with a SELECT statement in the same copy, unload, or load step; 
however, both may be used following a COPY statement for a copy or load 
operation. 


The format of the EXCLUDE statement is: 


where: 


MEMBER=((] membername! [, membername2 ...[)| 
specifies members on the input data set that are not to be copied, unloaded, or 
loaded to the output data set. The members are not deleted from the input 
data set unless the entire data set is deleted. (This can be done by specifying 
DISP=DELETE in the operand field of the input DD job control statement.) 
Each member name specified within one copy step must be unique. 


Note: The control statement operation and keyword parameter can be 
abbreviated to their initial letters; EXCLUDE can be abbreviated to E and 
MEMBER can be abbreviated to M. 


The following examples illustrate some of the uses of IEBCOPY. Table 11 can 
be used as a quick reference guide to IEBCOPY examples. The numbers in the 
‘“Example’’ column point to examples that follow. 
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Table 11. IEBCOPY Example Directory 


Operation Device Comments Example 


COPY 2314 Disk Full Copy. The input and output 
data sets are partitioned. l 7 
COPY 2314 Disk, Multiple input partitioned data sets. J 
3330 Disk Fixed-blocked and fixed record formats. 2 
COPY 3330 Disk, All members are to be copied 
2314 0r Identically named members on the 
2319 Disk! output data set are to be replaced. 
The input and output data sets are 
partitioned. 3 
COPY 3330 Disk, Selected members are to be copied. 


2314 Disk Variable-blocked data set is to be 
created. Record formats are variable- 
blocked and variable. The input and 
output data sets are partitioned. 4 


COPY 3330 Disk, Selected members are to be copied. 
2314 Disk One member is to replace an 
identically named member on the 
output data set. The input and 
output data sets are partitioned. 5 


COPY 2314 Disk, Selected members are to be copied. 
3330 Disk, Members found on the first input data set 
and 2305 Fixed replace identically named members on 
Head Storage The output data set. The input and 


output data sets are partitioned. 6 
COPY 2314 Disk Selected members are to be copied. 

Two members are to be renamed. One 

renamed member ts to replace an 

identically named member on the 

output data set. The input and 

output data sets are partitioned. 7 
COPY 2314 Disk Exclusive Copy. Fixed-blocked and 

fixed record formats. The input and 

output data sets are partitioned. 8 ; 
COPY and 2314 Disk Copy a partitioned data set to 
Compress 2400 tape tape (unload) and compress in 
in Place place if the first step is successful. 9 
COPY and 3330 Disk, Full copy to be followed by a compress- 
Compress- 2314 Disk in-place of the output data set. Replace 
in-place specified for one input data set. The 

input and output data sets are 

partitioned. 10 
COPY 2314 Disks Multiple copy operations. The input and 

output data sets are partitioned. 11 
COPY 2314 Disks Multiple copy operations. 12 
Unload 2314 Disk, A partitioned data set is to be 

2400 tape unloaded to tape. 13 
Load 2400 tape, An unloaded data set is to be loaded 
2314 Disk to disk. 14 

Unload and 2314 Disks, A partitioned data set is to be loaded 
COPY 2400 tape to tape to create a backup copy. If 

the unload is successful, the partitioned 

data set is compressed in place. 15 
Unload, 3330 Disk, Selected members are to be unloaded, 
Load, and 2400 tape, loaded, and copied. The input data set 
COPY 2314 Disk is partitioned; the output data set is 

sequential. 16 
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' The 2319 disk is functionally equivalent to the 2314 disk; 
to use the 2319, specify 2314 in the control statement. 


IEBCOPY Example 1 


IEBCOPY copy, unload, and load operations are specified by a combination of 
job control language and utility control statements. The OUTDD and INDD 
keyword parameters on COPY statements name DD statements that define the 
input and output data sets to be copied, unloaded, or loaded. For example: 


Jf COPY JOB accountnb, 'name',MSGLEVEL=(1,1) 
//JOBSTEP EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//IN DD DSN=xXXxxx, UNIT=yyyy, VOL=SER=yyyyyy,DISP=OLD 
7 fOUr DD DSN=XXxXxx, UNIT=yyyy, VOL=SER=yyyyyy, 

// DISP=NEW, SPACE=xxxx 

JF SYSUTS DD DSN=TEMP1,UNIT=SYSDA,DISP=(NEW,DELETE), 
if SPACE=CCYL; Coy 2))) 

//SYSUT4 DD DSNAMBE=TEMP2,UNIT=DA,DISP=( NEW, DELETE ), 
ff SPACE=(CY hy (2;,2)) 

//SYSIN DD * 

yt COPY OUTDD=OUT, INDD=IN 


The INDD parameter names the IN DD statement as the statement that contains 
the identification of the input data set. 


The OUTDD parameter names the OUT DD statement as the statement that 
contains the indentification of the output data set. 


The characteristics of the input and output data sets depend on the operation to 


be 


In 


performed, as follows: 


If a data set is to be copied, the input and output data sets must both be 
partitioned data sets. 


If a data set is to be loaded, the input data set may be either partitioned or 
sequential; the output data set must be partitioned. 


If a data set is to be unloaded, the input data set must be either a partitioned 


data set or a sequential data set that was created as a result of a previous 


unload operation; the output data set must be sequential. The output data set 
may reside on either a direct access or tape volume. If the output data set is to 


reside on a direct access volume, the organization of the data set must be 
specified as sequential. To specify sequential organization for a direct access 


data set, specify the SPACE parameter, omitting the directory or index value. 


this example, a partitioned data set (DATASETS) is to be copied from one 


disk volume to another. Figure 6 shows the input and output data sets before and 
after processing. 


The example follows: 


/ /COPY JOB O06#990,MCEWAN 

//JOBSTEP EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//INOUT4 DD DSNAME=DATASET4 , UNIT=2314, VOL=SER=111112, 
// DISP=( NEW,KEEP),SPACE=(TRK,(3,1,2)) 

//TNOUT3 DD DSNAME=DATASETS , UNIT=2314, VOL=SER=111113, 
7 /-DISPSOLD 

//SYSUT3 DD UNIT=2314,SPACE=(TRK,(1)) 

//SYSUT4 B16. UNIT=2314,SPACE=( TRK, (1) ) 

//SYSIN DD * 


COPYOPER COPY OUTDD=INOUT4, INDD=INOUTS5 


/* 
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Figure 6. Copying a Partitioned Data Set—Full Copy 


The control statements are discussed below: 


INOUT4 DD defines a partitioned data set (DATASET4). This data set is 
new and is to be kept after the copy operation. Five tracks are allocated for 
the data set on a 2314 volume. Two blocks are allocated for directory entries. 


INOUTS DD defines a partitioned data set (DATASETS), which resides on a 
2314 volume and contains two members (A and C). 


SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement. 


COPY indicates the start of the copy operation. The absence of a SELECT or 
EXCLUDE statement causes a default to a full copy. The OUTDD parameter 
specifies INOUT4 as the DD statement for the output data set (DATASET4); 
the INDD parameter specifies INOUTS as the DD statement for the input 
data set. After the copy operation is finished, the output data set 
(DATASET4) will contain the same members that are on the input data set 
(DATASETS); however, there will be no embedded, unused space on 
DATASET4. 


The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 
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In this example, members are to be copied from three input partitioned data sets 
(DATASET1, DATASETS, and DATASET6) to an existing output partitioned 
data set (DATASET2). The sequence in which the control statements occur 
controls the manner and sequence in which partitioned data sets are processed. 
Figure 7 shows the input and output data sets before and after processing. 
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Figure 7. Copying from Three Input Partitioned Data Sets 


The example follows: 


Jf COPY JOB 060#990,MCEWAN 
//JOBSTEP EXEC PGM=IEBCOPY 
f/SYSPRINT DD SYSOUT=A 


J / NOU! DD DSNAMBE=DATASET1,UNIT=2314,VOL=SER=111112, 
// DISP=(OLD, KEEP ) 


//INOUT5 DD DSNAME=DATASETS5, UNIT=3330,VOL=SER=111114, 
// DISP=OLD 

//INOUT2 DD DSNAME=DATASET2,UNIT=3330,VOL=SER=111115, 
if - DISP=COLD, KEEP) 

J 7 INOUTG DD DSNAME=DATASET6, UNIT=3330, VOL=SER=11111/7, 
if DLSPSCOLD, DELETE) 

JASYSUTS DD UNIT=2314,SPACE=( TRK,( 1) ) 

7 (S1LSUT4S DD UNIT=2314,SPACE=( TRK,( 1) ) 

~SSTSIN DD * 


COPYOPER COPY. OUTDD=INOUT2 
INDD=INOUT1 
INDD=INOUT6 
INDD=INOUT5 
/* 
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The control statements are discussed below: 


INOUT1 DD defines a partitioned data set (DATASET1). This data set, 
which resides on a 2314 volume, contains three members (A, B, and F) in 
fixed format with a logical record length of 80 bytes and a block size of 80 
bytes. 


INOUTS DD defines a partitioned data set (DATASETS), which resides on a 
3330 volume. This data set contains two members (A and C) in fixed-blocked 
format with a logical record length of 80 bytes and a block size of 160 bytes. 


INOUT2 DD defines a partitioned data set (DATASET2), which resides on a 
3330 volume. This data set contains two members (C and E) in fixed-blocked 
format. The members have a logical record length of 80 bytes and a block size 
of 240 bytes. 


INOUT6 DD defines a partitioned data set (DATASET®6), which resides on a 
3330 volume. This data set contains three members (B, C, and D) in 
fixed-blocked format with a logical record length of 80 bytes and a block size 
of 400 bytes. This data set is to be deleted when processing is completed. 


SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement and three INDD statements. 


COPY indicates the start of the copy operation. The absence of a SELECT or 
EXCLUDE statement causes a default to a full copy. The OUTDD parameter 
specifies INOUT2 as the DD statement for the output data set (DATASET2). 


The first INDD statement specifies INOUT1 as the DD statement for the first 
input data set (DATASET1) to be processed. All members (A, B, and F) are 
copied to the output data set (DATASET2). 


The second INDD statement specifies INOUT®6 as the DD statement for the 
second input data set (DATASET6) to be processed. Processing occurs, as 
follows: (1) members B and C, which already exist on DATASET2, are not 
copied to the output data set (DATASET2), (2) member D is copied to the 
output data set (DATASET2), and (3) all members on DATASET6 are lost 
when the data set is deleted. 


The third INDD statement specifies INOUTS as the DD statement for the 
third input data set (DATASETS) to be processed. No members are copied to 
the output data set (DATASET2) because all of them exist on DATASET2. 


The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 


In this example, members are to be copied from an input partitioned data set 
(DATASET6) to an existing output partitioned data set (DATASET2). In 
addition, all copied members are to replace identically named members on the 
output partitioned data set. 


Figure 8 shows the input and output data sets before and after processing. 


The example follows: 


/ /COPY JOB 06#990,MCEWAN 

//SJOBSTEP EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//INOUT2 DD DSNAME=DATASET2, UNIT T=2314, VOL=SER=111113, 
// DISP=OLD 

//INOUT6 DD DSNAME=DATASET6, UNIT=3330, VOL=SER=111117, 
iJ DA GP=COLDE KEEP) 

JISTSUTS. DD UNIT=2314,SPACE=( TRK,(1)) 

//SYSUT4 = DD UNIT=2314,SPACE=( TRK,(1)) 

//SYSIN DD x 


COPYOPER COPY OUTDD=INOUT2 
INDD=( ( INOUT6,R)) 
/* 
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Figure 8. Copy Operation with “Replace” Specified on the Data Set Level 
The control statements are discussed below: 


e INOUT2 DD defines a partitioned data set (DATASET2), which resides on a 
2314 volume. This data set contains two members (C and E). 


e INOUT®6 DD defines a partitioned data set (DATASET®6), which resides on a 
3330 volume. This data set contains three members (B, C, and D). 


¢ SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


e SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


« SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement and an INDD statement. 
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¢ COPY indicates the start of the copy operation. The absence of a SELECT or 
EXCLUDE statement causes a default to a full copy. The OUTDD parameter 
specifies INOUT2 as the DD statement for the output data set (DATASET2). 


¢ INDD specifies INOUT6 as the DD statement for the input data set 
(DATASET6). Members B, C, and D are copied to the output data set 
(DATASET2). The pointer in the output data set directory is changed to point 
to the new (copied) member C; thus, the space occupied by the old member 
C is embedded unused space. Member C is copied even though the output 
data set already contains a member named ‘‘C”’ because the replace option is 
specified for all identically named members on the input data set; that is, the 
replace option is specified on the data set level. 


The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 


In this example, five members (A, C, D, E, and G) are to be selected from two 
input partitioned data sets (DATASET6 and DATASET3) to be copied to a new 
output partitioned data set (DATASET4). Figure 9 shows the input and output 
data sets before and after processing. 
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Figure 9. Copying Selected Members with Reblocking and Deblocking 


J 


The example follows: 


//COPY JOB 06#990 , MCEWAN 

//JOBSTEP EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//INOUT2 DD DSNAME=DATASET2, UNIT=2314, VOL=SER=111114, 
// DISP=(OLD,DELETE) 

//INOUT6 DD DSNAME=DATASET6, UNI T=3330, VOL=SER=111117, 
// DISP=(OLD,KEEP ) 

//TNOUT4 DD DSNAME=DATASET4 , UNI T=3330, VOL=SER=111116, 


// DISP=(NEW,KEEP ),SPACE=(TRK,(5,,2)), 
// DCB=( RECFM=VB, LRECL=96, BLKSIZE=300 ) 


Jf STSUTS DD UNIT=2314,SPACE=( TRK,(1)) 
J /SYSUT4 DD UNI T=2314,SPACE=( TRK,( 1 ) ) 
A4 SLSIN DD * 

COPYOPER GORY OUTDD=INOUT4 


/* 


INDD=INOUT6 
INDD=INOUT2 
SELECT MEMBER=C,D,E,A,G 


The control statements are discussed below: 


INOUT2 DD defines a partitioned data set (DATASET2), which resides on a 
2314 volume. This data set contains two members (C and E) in 
variable-blocked format with a logical record length of 96 bytes and a block 
size of 500 bytes. This data set is to be deleted when processing is completed. 


INOUT®6 DD defines a partitioned data set (DATASET6), which resides on a 
3330 volume. This data set contains three members (B, C, and D) in variable 
format with a logical record length of 96 bytes and a block size of 100 bytes. 


INOUT4 DD defines a partitioned data set (DATASET4). This data set is Fe 
new and is to be kept after the copy operation. Five tracks are allocated for 

the data set on a 3330 volume. Two blocks are allocated for directory entries. 

In addition, records are to be copied to this data set in variable-blocked 

format with a logical record length of 96 bytes and a block size of 300 bytes. 


SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement, two INDD statements, and a SELECT 
statement. 


COPY indicates the start of the copy operation. The presence of a SELECT 
Statement causes a selective copy. The OUTDD parameter specifies INOUT4 
as the DD statement for the output data set (DATASET4). 


The first INDD statement specifies INOUT6 as the DD statement for the first 
input data set (DATASET6) to be processed. The members specified on the 
SELECT statement are searched for. The found members (C and D) are 
copied to the output data set (DATASET4) in the order in which they reside 
on the input data set, that is, in TTR order. In this case, member D is copied 
first, and then member C is copied. 


The second INDD statement specifies INOUT2 as the DD statement for the 
second input data set (DATASET2) to be processed. The members specified 
on the SELECT statement and not found on the first input data set are 
searched for. The found member (E) is copied onto the output data set 
(DATASET4). All members on DATASET2 are lost when the data set is 
deleted. 
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e SELECT specifies the members to be selected from the input data sets 
(DATASET6 and DATASET2) to be copied to the output data set 
(DATASET4). 


The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 


In this example, two members (A and B) are to be selected from two input 
partitioned data sets (DATASETS and DATASET6) to be copied to an existing 
output partitioned data set (DATASET1). Member B is to replace an identically 
named member that already exists on the output data set. Figure 10 shows the 
input and output data sets before and after processing. 


The example follows: 


/ /COPY JOB 00#990,MCEWAN 

7 PIOBSTEP EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

J /INOUT DD DSNAME=DATASET 1, UNIT=2314, VOL=SER=111112, 
// DISP=(OLD,KEEP ) 

//INOUT6 DD DSNAME=DATASET6, UNI T=3330, VOL=SER=111115, 
// DISP=OLD 

JFINOUES DD DSNAME=DATASET5, UNI T=2314, VOL=SER=111116, 
{7 DISP=( OLD; KEEP } 

f/f SXSUT3 DD UNIT=2314,SPACE=( TRK,( 1) ) 

//SYSUT4 DD UNIT=2314,SPACE=( TRK,(1)) 

JP SISIN DD * 

COPYOPER COPY OUTDD=INOUT 1 


INDD=INOUT5, INOUT6 
SELECT MEMBER=((B,,R),A) 
/* 


3 


Input 
DATASETS5 


ee: eee 


Directory 


bh % 

Usused Si 

on 

eae ye 

A ie 

——* 

sy 

= 

=— ‘ee 

Available ». 

~ 
Output ' 
DATASET 1 d 


Copy Placing 


member | 
ae 
oN 
Directory Directory ! ae 
Directory pe 
ae 
Member Member Member xy} 
F F ee 
p Bs, 
Unused Unused Un pe 4 
sah a y int 
Otd member B : * 
—_ ; ~~ not pointed at SB-8by 
Available PP 5 Available’ oe a 
Before After After 
copy — processing processing 
operation DATASETS DATASET6 


Figure 10. Selective Copy with ‘‘Replace’’ Specified on the Member Level 
The control statements are discussed below: 


e INOUT1 DD defines a partitioned data set (DATASET1). This data set 
resides on a 2314 volume and contains three members (A, B, and F). 


¢ INOUT6 DD defines a partitioned data set (DATASET®6). This data set 
resides on a 3330 volume and contains three members (B, C, and D). 


¢ INOUTS DD defines a partitioned data set (DATASETS). This data set 
resides on a 2314 volume and contains two members (A and C). 


¢ SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


¢ SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


e SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement, an INDD statement, and a SELECT 
statement. 


e COPY indicates the start of the copy operation. The presence of a SELECT 
statement causes a selective copy. The OUTDD parameter specifies INOUT1 
as the DD statement for the output data set (DATASET1). 
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e INDD specifies INOUTS as the DD statement for the first input data set 


(DATASETS) to be processed and INOUT®6 as the DD statement for the 
second input data set (DATASET6) to be processed. Processing occurs, as 
follows: (1) selected members are searched for on DATASETS, (2) member A 
is found, but is not copied to the output data set because it already exists on 
DATASET?2 and the replace option is not specified, (3) selected members not 
found on DATASETS are searched for on DATASET6, and (4) member B is 
found and copied to the output data set (DATASET1), even though a member 
named B already exists on the output data set, because the replace option is 
specified for member B on the member level. The pointer in the output data 
set directory is changed to point to the new (copied) member B; thus, the 
Space occupied by the old member B is unused. 


SELECT specifies the members to be selected from the input data sets 
(DATASETS and DATASET6) to be copied to the output data set 
(DATASET1). 


The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 


In this example, two members (A and B) are to be selected from two input 
partitioned data sets (DATASETS and DATASET6) to be copied to an existing 
output partitioned data set (DATASET1). All members found on DATASETS 
are to replace identically named members on DATASET1. Figure 11 shows the 
input and output data sets before and after processing. 


Input 
DATASET5 


Input 
DATASET6 


Directory 
A 


Unusea 


Directory 
BCD 


Member Member B 


Unused D 


Availabia 


Avallable 


Output 
DATASET1 


Directory 


Before 


operation 
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The example follows: 


//COPY JOB 064990, MCEWAN 

//SJOBSTEP EXEC PGM=1LEBCOPY 

//SYSPRINT DD SYSOUT=A 

//tNOUT1 DD DSNAME=DATASET 1, UNIT=3330, VOL=SER=111112, 
// DISP=(OLD,KEEP ) 

//INOUT5 DD DSNAME=DATASETS , UNIT=2314, VOL=SER=111114, 
// DISP=(OLD,DELETE) 

//INOUT6 DD DSNAME=DATASET6, UNIT=2305, VOL=SER=111115, 
// DISP=(OLD, KEEP ) 

//SYSUT3 DD UNI T=2314,SPACE=( TRK,(1)) 

JISYSUTL: Dd UNIT=2314,SPACE=( TRK,(1)) 

//SYSIN DD * 

COPYOPER COPY OUTDD=INOUT1 


/* 


INDD=( ( INOUT5,R), INOUT® ) 
SELECT MEMBER=(A,B) 


The control statements are discussed below: 


INOUT1 DD defines a partitioned data set (DATASET1). This data set 
resides on a 3330 volume and contains three members (A, B, and F). 


INPUTS DD defines a partitioned data set (DATASETS). This data set 
contains two members (A and C) and resides on a 2314 volume. This data set 
is to be deleted when processing is completed. 


INOUT®6 DD defines a partitioned data set (DATASET6). This data set 
contains three members (B, C, and D) and resides on a 2305 volume. 


SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement, an INDD statement, and a SELECT 
statement. 


COPY indicates the start of the copy operation. The presence of a SELECT 
statement causes a selective copy. The OUTDD operand specifies INOUT1 as 
the DD statement for the output data set (DATASET1). 


INDD specifies INOUTS as the DD statement for the first input data set 
(DATASETS) to be processed and INOUT6 as the statement for the second 
input data set (DATASET6) to be processed. Processing occurs, as follows: 
(1) selected members are searched for on DATASETS, (2) member A is 
found and copied to the output data set (DATASET1) because the replace 
option was specified on the data set level for DATASETS, (3) member B, 
which was not found on DATASETS is searched for and found on 
DATASET6, (4) member B is not copied because DATASET1 already 
contains a member called member B and the replace option is not specified for 
DATASET6. The pointer in the output data set directory is changed to point 
to the new (copied) member A; thus, the space occupied by the old member 
A is unused. 


SELECT specifies the members to be selected from the input data sets 
(DATASETS and DATASET6) to be copied to the output data set 
(DATASET1). 


The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 
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In this example, four members (A, B, C, and D) are to be selected from an input 

partitioned data set (DATASET6) to be copied to an existing output partitioned 

data set (DATASET3). Member B is to be renamed H; member C is to be 

renamed J; and member D is to be renamed K. In addition, member C (renamed 2 
J) is to replace the identically named member (J) on the output partitioned data | 
set. Figure 12 shows the input and output data sets before and after processing. 


The example follows: 


pf COPY JOB #990 ,MCEWAN 

J /SOBSTEP” EXEC PGM=LEBCOPY 

//SYSPRINT DD SYSOUT=A 

{/ELNOUTS DD DSNAME=DATASET3 , UNI T=2314, VOL=SER=111114, 
// DISP=( OLD, KEEP ) 

/ /INOUT6 DD DSNAME=DATASET6, UNI T=2314,VOL=SER=111117, 
7? DISP=(OLD, DELETE) 

J7SYSUT3 DD UNIT=2314,SPACE=( TRK,( 1 ) ) 

//SYSUT4 DD UNIT=2314,SPACE=( TRK,( 1 ) ) 

//SYSIN DD * 

COPTOPRER COPY OUTDD=INOUT3 


INDD=INOUT6 
SELECT MEMBER=(:(ByH)>( C,d¢R)) AyD KR) ) 
/* 
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Figure 12. Renaming Selected Members Using IEBCOPY 
The control statements are discussed below: 


e INOUT3 DD defines a partitioned data set (DATASET3). This data set 
contains four members (D, G, H, and J) and resides on a 2314 volume. 
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e INOUT6 DD defines a partitioned data set (DATASET6). This data set 
contains three members (B, C, and D) and resides on a 2314 volume. 
DATASETB6 is to be deleted when processing is completed; thus, all members 
on this data set are lost. 


e SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


e SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


e SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement, an INDD statement, and a SELECT 
statement. 


e COPY indicates the start of the copy operation. The presence of a SELECT 
statement causes a selective copy. The OUTDD parameter specifies INOUT3 
as the DD statement for the output data set (DATASET3). 


e INDD specifies INOUT®6 as the DD statement for the input data set 
(DATASET6). Processing occurs, as follows: (1) selected members are 
searched for on DATASET®6, (2) member B is found, but is not copied to 
DATASET3 because its intended new name (H) is identical to the name of a 
member (H), which already exists on the output data set, and replace is not 
specified, (3) member C is found and copied to the output data set 
(DATASET3), although its new name (J) is identical to the name of a 
member (J), which already exists on the output data set, because the replace 
option is specified for the renamed member, and (4) member D is copied onto 
the output data set (DATASET3) because its new name (K) does not already 
exist there. 


e SELECT specifies the members to be selected from the input data set 
(DATASET6) to be copied to the output data set (DATASET3). 


The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 


In this example, five members (A, B, C, J, and L) are to be excluded from the 
copy operation when each of the input partitioned data sets (DATASET1, 
DATASET3, and DATASET6) is processed. In addition, replace is specified for 
the last input partitioned data set (DATASET6) to be processed; thus, with the 
exception of the members specified on the EXCLUDE statement, all members on 
DATASET6 will replace any identically named members on the output 
partitioned data set (DATASET4). Figure 13 shows the input and output data 
sets before and after processing. 


IEBCOPY Program 83 


84 OS/VS Utilities 


Input Input Input 
DATASET1 DATASET3 DATASET6 


Directory eee i Tae 6 


Member B 


ee 


+ ‘ | 4 7 s i; a - . + 2 
Output i Copy rep ks ding 
DATASET4 si z member 9 
‘ ae 


a 2a 


Directory Directory 
DFGH DFG 


Member F 


x, > ; 


yy P e pe 
ie D not pointed 
at 
ct ¥ 


_— 


— 


Before After After After 


oe 


copy processing processing processing 
operation DATASET! DATASET3 DATASET6 


Figure 13. Exclusive Copy with “Replace” Specified for One Input Partitioned Data Set 


The example follows: 


7 fCOPY JOB 06#990,MCEWAN 

{/fIOBSIEP “EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

77 INOUTA DD DSNAME=DATASET 1 , UNIT=2314, VOL=SER=111112, 
// DISP=(OLD,KEEP } 

if ENOULS DD DSNAME=DATASET3 , UNIT=2314, VOL=SER=111114, 
// DISP=OLD 

//INOUT4 DD DSNAME=DATASET4, UNIT=2314, VOL=SER=111115, 


// DISP=(NEW, KEEP ),SPACE=(TRK,(3,1,2)), 
// DCB=( LRECL=100, RECFM=FB, BLKSIZE=400 ) 


//INOUT6 ~~ DD DSNAME=DATASET6 , UNIT=2314, VOL=SER=111116, 
// DISP=OLD 

//SYSUT3 DD UNIT=2314, SPACE=( TRK,(1)) 

//SYSUT4 DD UNIT=2314,SPACE=( TRK,(1)) 

//SYSIN DD 

COPYOPER COPY OUTDD=INOUT4 , INDD=INOUT1, INOUT3,( INOUTG6,R) 


EXCLUDE MEMBER=A,J,B,L,C 
/* 


The control statements are discussed below: 


e INOUT1 DD defines a partitioned data set (DATASET1). This data set 
contains three members (A, B, and F) and resides on a 2314 volume. The 
record format is fixed blocked with a logical record length of 100 bytes and a 
block size of 400 bytes. 


e INOUT3 DD defines a partitioned data set (DATASET3), which resides on a 
2314 volume. This data set contains four members (D, G, H, and J) in 
fixed-blocked format with a logical record length of 100 bytes and a block 
size.of 600 bytes. 


e INOUT4 DD defines a new partitioned data set (DATASET4). Five tracks are 
allocated for the copied members on a 2314 volume. Two blocks are allocated 
for directory entries. In addition records are to be copied to this data set in 
fixed-blocked format with a logical record length of 100 bytes and a block 
size of 400 bytes. 


e INOUT6 DD defines a partitioned data set (DATASET6). This data set 
contains three members (B, C, and D) in fixed format. The records have a 
logical record length of 100 bytes and a block size of 100 bytes. This data set 
resides on a 2314 volume. 


e SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


« SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


e SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement and an EXCLUDE statement. 


¢ COPY indicates the start of the copy operation. The presence of an 
EXCLUDE statement causes an exclusive copy. The OUTDD parameter 
specifies INOUT4 as the DD statement for the output data set (DATASET4). 
The INDD parameter specifies INOUT1 as the DD statement for the first 
input data set (DATASET1) to be processed, INOUT3 as the DD statement 
for the second input data set (DATASET3) to be processed, and INOUT6 as 
the DD statement for the last input data set (DATASET6) to be processed. 
Processing occurs, as follows: (1) member F, which is not named on the 
EXCLUDE statement, is copied from DATASET1, (2) members D, G, and H, 
which are not named on the EXCLUDE statement, are copied from 
DATASET3, and (3) member D is copied from DATASET®6 because the 
replace option is specified for non-excluded members. The pointer in the 
output data set directory is changed to point at the new (copied) member D; 
thus, the space occupied by the o/d member D (copied from DATASETS3) is 
unused. 


e EXCLUDE specifies the members to be excluded from the copy operation. 
The named members are excluded from all of the input partitioned data sets 
specified in the copy operation. 


The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 
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In this example, a partitioned data set is to be unloaded to a tape volume to 
create a backup copy of the data set. If this step is successful, the partitioned 
data set is to be compressed in place. 
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The example follows: 


//SAVE JOB 123456,'name',MSGLEVEL=(1,1) 
//STEP1 EXEC PGM=I1EBCOPY 
//SYSPRINT DD  SYSOUT=A 
//INPDS DD DSNAME=PARTPDS, UNIT=2314,VOL=SER=PCP001, 
// DISP=OLD | 
/ / BACKUP DD DSNAME=SAVDATA, UNIT=2400,VOL=SER=TAPEO3, ~d 
// DISP=(NEW,KEEP ), LABEL=( ,SL) 
//SYSUT3 DD DSNAME=TEMP1,UNIT=2314,VOL=SER=111111, 
// DISP=(NEW,DELETE ),SPACE=(80,(60,45)) 
//SYSIN DD * 
COPY OUTDD=BACKUP, INDD=INPDS 
/* 
//STEP2 EXEC PGM=IEBCOPY,COND=(0,NE), 


// PARM='SIZE=99999999K' 
//SYSPRINT DD  SYSOUT=A 


/ /COMPDS DD DSNAME=PARTPDS,UNIT=2314,DISP=OLD, 

// VOL=SER=PCPO001 

//SYSUT3 DD  DSNAME=TEMPA,UNIT=2314,VOL=SER=111111, 
// DISP=(NEW,DELETE ), SPACE=(80,(60,45)) 

//SYSUT4 DD  DSNAME=TEMPB,UNIT=2314,VOL=SER=111111, 
// SPACE=( 256,(15,1)),DCB=KEYLEN=8 

//SYSIN DD 


COPY OUTDD=COMPDS, INDD=COMPDS 
/* 


The control statements are discussed below: 


e INPDS DD defines a partitioned data set (PARTPDS) that resides on a 2314 
volume and has 700 members. The number of members is used to calculate 
the space allocation on SYSUT3. 


e BACKUP DD defines a sequential data set to hold PARTPDS in unloaded 
form. Block size information can optionally be added; this data set must be 
new. 


e SYSUT3 DD defines the temporary spill data set. J 


e SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement. 


e COPY marks the beginning of the unload operation; the absence of an 
EXCLUDE or SELECT statement causes the entire partitioned data set 
(INDD=INPDS) to be unloaded to a sequential data set 
(OUTDD=BACKUP). 


e The second EXEC statement marks the beginning of the compress-in-place 
operation. The SIZE parameter indicates that the buffers are to be as large as 
possible. The COND parameter indicates that the compress in place is to be 
performed only if the unload operation was successful. 


e COMPDS DD defines a partitioned data set (PARTPDS) that contains 700 
members and resides on a 2314 volume. 


e SYSUT3 DD defines the temporary spill data set to be used if there is not 
enough space in main storage for the input data set’s directory entries. 


e SYSUT4 DD defines the temporary spill data set to be used if there is not 
enough space in main storage for the output partitioned data set’s directory 
blocks. 


e SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement. 
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e COPY marks the beginning of the copy operation. The absence of a SELECT 
or EXCLUDE statement causes a default to a full copy. Because the same DD 
statement is specified for both the INDD and OUTDD operands, the data set 
is compressed in place. 


The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. Note, however, that 
the SYSUT4 data set is never used for an unload operation. 


Note: For an unload operation, only one INDD data set may be specified for one 
OUTDD data set. 


In this example, two input partitioned data sets (DATASETS and DATASET6) 
are to be copied to an existing output partitioned data set (DATASET1). In 
addition, all members on DATASET®6 are to be copied; members on the output 
data set that have the same names as the copied members are replaced. After 
DATASET6 is processed, the output data set (DATASET1) is to be compressed 
in place. Figure 14 shows the input and output data sets before and after 
processing. 
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Figure 14. Compress-in-Place Following Full Copy with ‘Replace’ Specified 
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The example follows: 


/ /COPY JOB 06#990,MCEWAN 

//JOBSTEP EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//TINOUT1 DD DSNAME=DATASET1, UNI T=2314, VOL=SER=111112, 
// DISP=(OLD,KEEP ) ) 
//TNOUT5 DD DSNAME=DATASETS , UNI T=3330,VOL=SER=111114, 
J} BESP=0LD 

//TNOUT6 DD DSNAME=DATASET6, UNI T=3330, VOL=SER=111115, 
// DISP=( OLD, KEEP) 

//SYSUT3 DD UNIT=2314,SPACE=(TRK,(1)) 

//SYSUT4 DD UNI T=2314,SPACE=( TRK,(1)) 

//SYSIN DD # 


GOPYOPER COPY OUTDD=INOUT 1 
INDD=INOUT5,( INOUT6,R), INOUT1 
/* 


The control statements are discussed below: 


¢ INOUT1 DD defines a partitioned data set (DATASET1). This data set 
contains three members (A, B, and F) and resides on a 2314 volume. 


¢ INOUTS DD defines a partitioned data set (DATASETS). This data set 
contains two members (A and C) and resides on a 3330 volume. 


¢ INOUT6 DD defines a partitioned data set (DATASET6). This data set 
contains three members (B, C, and D) and resides on a 3330 volume. 


¢ SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


¢ SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


¢ SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement and an INDD statement. ) 


« COPY indicates the start of the copy operation. The OUTDD operand 
specifies INOUTI as the DD statement for the output data set (DATASET1). 
The absence of a SELECT or EXCLUDE statement causes a default to a full 


copy. 


e INDD specifies INOUTS as the DD statement for the first input data set 
(DATASETS) to be processed. It then specifies INOUT6 as the DD statement 
for the second input data set (DATASET6) to be processed; in addition, the 
replace option is specified for all members copied from DATASETO. Finally, it 
specifies INOUT1 as the DD statement for the last input data set 
(DATASET1) to be processed; this causes a compress-in-place of DATASET1 
because it is also specified as the output data set. Processing occurs, as 
follows: (1) member A is not copied from DATASETS onto the output data 
set (DATASET1) because it already exists on DATASET and the replace 
option was not specified for DATASETS, (2) member C is copied from 
DATASETS to the output data set (DATASET1), occupying the first available 
space, and (3) all members are copied from DATASET6 to the output data 
set (DATASET1), immediately following the last member. Members B and C 
are copied even though the output data set already contains members with the 
Same names because the replace option is specified on the data set level. The 
pointers in the output data set directory are changed to point.to the new 
members B and C; thus, the space occupied by the old members B and C is 
unused. The members currently on DATASETI are compressed in place, 
thereby eliminating embedded unused space. 
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The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 
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In this example, members are to be selected, excluded, and copied from input 
partitioned data sets onto an output partitioned data set. This example is 
designed to illustrate multiple copy operations. Figure 15 shows the input and 
Output data sets before and after processing. 


IEBCOPY Program 89 


First copy operation 


Input 


Outout 
DATASETA 


Directory 
MA MB MC MD 
ME MF MG 


MB 

MC 
Unused 

MD 


Unused 


Available 


Before 


copy 
operation 


90 OS/VS Utilities 


DATASETA 


Directory 
MA MB MC MD 
ME MF MG 


Member MA 


Unused 


Unused 


Available 


Directory 
MA MB MC MD 
ME MF MG 


Member MA 


Available 


After 


compressing 
in place 
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C' 


The example follows: 


J PCOPY JOB 06#990,MCEWAN 
//JOBSTEP EXEC PGM=IEBCOPY 
//SYSPRINT DD SYSOUT=A 
//INOUTA DD DSNAME=DATASETA, UNIT=2314, VOL=SER=111113, 
// DISP=OLD 
//INOUTB DD DSNAME=DATASETB, UNIT=2314, VOL=SER=111115, 
// DISP=(OLD,KEEP ) 
//INOUTC DD DSNAME=DATASETC, UNIT=2314, VOL=SER=111114, 
// DISP=(OLD,KEEP) 
//INOUTD DD DSNAME=DATASETD, UNIT=2314, VOL=SER=111116, 
// DISP=OLD 
//INOUTE DD DSNAME=DATASETE, UNIT=2314, VOL=SER=111117, 
// DISP=OLD 
//INOUTX DD DSNAME=DATASETX , UNIT=2314, VOL=SER=111112, 
// DISP=(NEW,KEEP ), SPACE=(TRK,(3,1,2)) 
J/SYSUT3, DD UNIT=2314,SPACE=( TRK,(1)) 
//SYSUT4 DD UNETS2314.,SPACE=(7RK. (139 
//SYSIN DD x 
COPERST1 COPY O=INOUTX, I=INOUTA 

COPY OUTDD=INOUTA, INDD=INOUTA 

INDD=INOUTB 
COPY O=INOUTA 


/* 


INDD=1NOUTD 
EXCLUDE MEMBER=MM 
INDD=INOUTC 
eps Wash Gall MEMBER=((ML,MD,R) ) 
INDD=INOUTE 


The control statements are discussed below: 


INOUTA DD defines a partitioned data (DATASETA). This data set contains 
eight members (MA, MB, MC, MD, ME, MF, MG, and MH) and resides on a 
2314 volume. 


INOUTB DD defines a partitioned data set (DATASETB). This data set 
resides on a 2314 volume and contains two members (MA and MJ). 


INOUTC DD defines a partitioned data set (DATASETC), which resides on a 
2314 volume. The data set contains four members (MF, ML, MM, and MN). 


INOUTD DD defines a partitioned data set (DATASETD). This data set 
resides on a 2314 volume and contains two members (MM and MP). 


INOUTE DD defines a partitioned data set (DATASETE). This data set 
contains four members (MD, ME, MF, and MT) and resides on a 2314 
volume. 


INOUTX DD defines a partitioned data set (DATASETX). This data set is 
new and is to be kept after the copy operation. Five tracks are allocated for 
the data set on a 2314 volume. Two blocks are allocated for directory entries. 


SYSUT3 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains two COPY statements, several INDD statements, a SELECT 
statement, and an EXCLUDE statement. 


The first COPY statement indicates the start of the first copy operation. This 
copy operation is done to create a backup copy of DATASETA, which is 
subsequently compressed in place. 
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e The second COPY statement indicates the start of another copy operation. 
The absence of a SELECT or EXCLUDE statement causes a default to a full 
copy; however, the same DD statement, INOUTA, is specified for both the 
INDD and OUTDD parameters, causing a compress-in-place of the specified 
data set. 


e INDD specifies INOUTB as the DD statement for the input data set J 
(DATASETB) to be copied. Only member MJ is copied because member MA 
already exists on the output data set. 


e The third COPY statement indicates the start of the third copy operation. The 
OUTDD parameter specifies INOUTA as the DD statement for the output data 
set (DATASETA). This copy operation contains more than one copy step. 


e The first INDD statement specifies INOUTD as the DD statement for the first 
input data set (DATASETD) to be processed. Only member MP is copied to 
the output data set (DATASETA) because member MM is specified on the 
EXCLUDE statement. 


e EXCLUDE specifies the member to be excluded from the first copy step 
within this copy operation. 


¢ The second INDD statement marks the beginning of the second copy step for 
this copy operation and specifies INOUTC as the DD statement for the 
second input data set (DATASETC) to be processed. Member ML is searched 
for, found, and copied to the output data set (DATASETA). Member ML is 
copied even though its new name (MD) is identical to the name of a member 
(MD) that already exists on the output data set, because the replace option is 
specified for the renamed member. 


e SELECT specifies the member to be selected from the input data set 
(DATASETC) to be copied to the output partitioned data set. 


e The third INDD statement marks the beginning of the third copy step for this : 
copy operation and specifies INOUTE as the DD statement for the last data J 
set (DATASETE) to be copied. Only member MT is copied because the other 
members already exist on the output data set. Because the INDD statement is 
not followed by an EXCLUDE or SELECT statement, a full copy is 
performed. 


The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 


The output data set is compressed in place first to save space because it is known 
that it contains embedded, unused space. 
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In this example, members are to be selected, excluded, and copied from input 
partitioned data sets to an output partitioned data set. This example is designed 
to illustrate multiple copy operations. Figure 16 shows the input and output data 
sets before and after processing. 
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The example follows: 


/ {COPY JOB 064990,MCEWAN 
//SOBSITEP EXEC PGM=I] EBCOPY 
//5YSPRINT DD SYSOUT=A 
//INOUTA DD DSNAME=DATAS=TA, NTT -2314, VOL=SER=111113, 
/# DISP=OLD 
//TNOUTB DD DSNAME=DATASE! 3, VYUL=SER=11:31°5, 
// DISP=(OLD,KEEP), UNIT=2314 
//ILNOUTC DD DSNAME=DATASE [i2, <8 =SER=111114, 
// DiBP= (OLD, KEEP TY; UNI TH23 14 
//INOUTD DD DSNAME=DATASE 22), YOL=SER=111116, 
// DISP=EOLD,UNIT=2314 
//INOUTE OD DSNAMF=DATAS=T? , JOL=SER=111117, 
if DISP=OLD;. T7493 14 
//SSUT 3 DD UNIT=2314,SPACKR=2: TRK,(17))} 
//SNSUT4S DD UN PTS2344,SPR@RSs TSK .( 171) 
J//SYSIN DD x 

COPY OUTDD=INOUTs 

INDD=INOUTE 
SELECT MEMBER-MA, MU 


PRES NOUS 
EACLUDE MPMBFR=MM, MN 


COPY O= LNOUT Bs DN it ee 

PSCC INOW Cs R ly 21. mele 
COPY O=FNOUTD, f=( Cathy IFM,F 
Si oe MEMBER=MM 


f# 
The contro! statements are discussed below: 


« [NOUTA DD defines a partitioned data set (DATASETA),. This data set 
contains three members (MA, MB, and MD) and resides on a 2314 volume. 


« INOUTB DD delines a partitioned data set (DATASETB). This data set 
resides on a 2314 volume and contains two members (MA and MJ). 


« INOUTC DD defines a partitioned data set (DATASETC). which resides on a 
2314 volume. This data set contains four members (MF, ML. MM. and MN). 


« INOUTD DD defines a partitioned data set (DATASETD). This data set 
resides On a 2314 volume and contains two members (MM and MP). 


e INOUTE DD defines a partitioned data set (DATASETE), which resides on a 
2314 volume. This data set contains three members (MA, MJ and MK). 


« SYSUT3 DD defines a temporary spill data set. One track 1s allocated on a 
2314 volume. 


« SYSUT4 DD defines a temporary spill data set. One track is allocated on a 
2314 volume. 


« SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains three COPY statements, SELECT and EXCLUDE 
statements, and several INDD statements. 


« The first COPY statement indicates the start of a copy Operation. The 
OUTDD operand specifies INOUTA as the DD statement for the output data 
set (DATASETA). 


« The first INDD statement specifies INOUTE as the DD statement for the first 
input data set (DATASETE) to be processed. Processing occurs, as follows: 
(|) member MA its searched for and found, but is not copied because the 
replace opuion is not specified, and (2) member MJ ts searched for, found, and 
copied to the output data set. Members are not searched for again after they 
are found. 
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¢ SELECT specifies the members (MA and MJ) to be selected from the input 
data set (DATASETE) to be copied. 


e The second INDD statement marks the end of the first copy step and the 
beginning of the second copy step within the first copy operation. It specifies 
INOUTC as the DD statement for the second input data set (DATASETC) to 
be processed. Members MF and ML, which are not named on the EXCLUDE 
statement, are copied because neither exists on the output data set. 


¢ EXCLUDE specifies the members (MM and MN) to be excluded from the 
second copy’ operation. 


« The second COPY statement indicates the start of another copy operation. 
The absence of a SELECT or EXCLUDE statement causes a default to a full 
copy. The O (QUTDD) parameter specifies INOUTB as the output data set 
(DATASETB). The INDD parameter specifies INOUTD as the first input data 
set (DATASETD) to be processed. Members MP and MM are copied to the 
Output data set. 


¢ INDD(I) specifies INOUTC as the DD statement for the second input data set 
(DATASETC) and INOUTB as the DD statement for the third input data set 
(DATASETB) to be processed. Members MF, ML, MM, and MN are copied 
from DATASETC. Member MM is copied, although it already exists on the 
output partitioned data sets, because the replace option is specified. Because 
DATASETB is also the data set specified in the OUTDD parameter, a 
compress-in-place takes place. (The pointer in the output set directory is 
changed to point to the new (copied) member MM; thus the space occupied 
by the replaced member MM is embedded, unused space.) 


e The third COPY statement indicates the start of another copy operation. The 
O (OUTDD) parameter specifies INOUTD as the DD statement for the 
output data set (DATASETD). The I (INDD) parameter specifies INOUTB as 
the DD statement for the input data set (DATASETB). 


¢ SELECT specifies the member (MM) to be selected from the input partitioned 
data set (DATASETB) to be copied. The replace option is specified on the 
data set level. 


The temporary spill data sets may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the SYSUT3 and 
SYSUT4 DD statements always appear in the job stream. 


Data sets used as input data sets in one copy operation can be used as output 
data sets in another copy operation, and vice versa. 


In this example, a partitioned data set (SYS1.LINKLIB) is to be unloaded to a 
tape volume. 
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The example follows: 


/ /UNLOAD JOB 246803, ‘name',MSGLEVEL=( 1,1 ) 
//STEP1 EXEC PGM=IEBCOPY,PARM='SIZE=100K' 
//SYSPRINT DD SYSOUT=A 
//INPDS DD DSNAME=SYS17.LINKLIB, UNIT=2314, 
// VOL=SER=666666, DISP=OLD 
/ /OUTTAPE DD DSNAME=LINKLIB, UNIT=2400, VOL=SER=TAPEOO, 
// LABEL=(,SL),DISP=( NEW, KEEP ) 
Jf SVOUTS DD DSN=TEMP1, UNIT=2314, VOL=SER=111111, 
// DISP=(NEW, DELETE ),SPACE=(80,(60,45)) 
//SYSIN DD * 
COPY OUTDD=OUTTAPE 

INDD=INPDS 

/* 


The control statements are discussed below: 


« EXEC specifies the execution of IEBCOPY. The PARM parameter specifies 
the size of the input/output buffer to be used. 


e INPDS DD defines a partitioned data set (SYS1.LINKLIB), which resides on 
a 2314 volume. This data set has 700 members; the number of members is 
used to calculate the space allocation for SYSUT3. 


¢ OUTTAPE DD defines a sequential data set to which SYS1.LINKLIB is to be 
unloaded.The unloaded data set is named LINKLIB. This data set must be 
new ; if a tape volume is used, it can be standard labeled or not labeled. 


¢ SYSUT3 DD defines a temporary spill data set on a 2314 volume. This data 
set is used if there is not enough space in main storage for the input 
partitioned data set’s directory entries. This data set may or may not be 
opened depending on the amount of main storage available; therefore, it is 
suggested that the statement always appear in the job stream. 


e SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY and INDD statement. 


e COPY indicates the start of an unload operation because the OUTDD 
parameter refers to OUTTAPE DD, which specifies a sequential output data 
set. Because of the absence of an EXCLUDE or SELECT statement, the 
entire data set is unloaded. 


e INDD refers to INPDS DD, which defines the input partitioned data set to be 
unloaded. Note that for an unload operation, only one INDD data set may be 
specified for each OUTDD data set. 


The SYSUT4 data set is never used for an unload operation. The SYSUT3 data 
set for an unload operation is used under the same conditions as it is used for a 
copy operation. 


Note: If too much space is allocated, the paging process slows down because the 
buffer areas are fixed. 


In this example, sequential data set created by an IEBCOPY unload operation is 
to be loaded. 


J 
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The example follows: 


77 LORD JOB 246803, 'name',MSGLEVEL=( 1,1) 

//STEPA EXEC PGM=IEBCOPY, PARM='SITZE=14588' 
//SYSPRINT DD SYSOUT=A 

//SEQIN DD DSNAME=UNLOADSET, UNIT=2400, LABEL=(,SL), 


// VOL=SER=TAPEO1,DISP=OLD 
/ /INOUT4 DD DSNAME=DATASET4, UNI T=2314, VOL=SER=231400, 
// DISP=(NEW,KEEP),SPACE=(CYL,(10,5,10)) 
JPSvouls DD DSN=TEMP1 ,UNIT=2314, VOL=SER=111111, 
7/ DISP=( NEW, DELETE), SPACE=( 80) 1:5, 1.39 
SI SYSIN DD - 
COPY OUTDD=INOUT4, INDD=SEQIN 


/* 
The control statements are discussed below: 


e EXEC specifies the execution of IEBCOPY. The PARM parameter allocates 
two tracks on a 2314 volume. If less space is specified, two tracks are 
allocated because two tracks are the minimum required by IEBCOPY when 
the unloaded data set’s block size does not exceed the track capacity. 


e SEQIN DD defines a sequential data set that was previously unloaded by 
IEBCOPY. The data set contains 28 members in sequential organization. 


e INOUT4 DD defines a partitioned data set on a 2314 volume. This data set 1s 
to be kept after the load operation. Ten cylinders are allocated for the data 
set; ten blocks are allocated for directory entries. 


e SYSUT3 DD defines a temporary spill data set on a 2314 volume. This data 
set is used if there is not enough space in main storage for the input data set’s 
directory entries. This data set may or may not be opened, depending on the 
amount of main storage available; therefore, it is suggested that the statement 
always appear in the job stream. Note that the space allocated for this data set 
is based on the number of members in the input data set. 


e SYSIN DD defines the control data set, which follows in the input stream. The 
data set contains a COPY statement. 


e COPY indicates the start of a load operation because the INDD parameter 
refers to SEQIN DD, which defines a sequential data set, and OUTDD refers 
to INOUT4 DD, which defines a direct access volume. 


Because the output data set in this example is new, the SYSUT4 data set is not 
needed. SYSUT4 should be specified, however, when the output data set is old. 


Note: Reblocking may be specified for the output partitioned data set. 


In this example, a partitioned data set is to be unloaded to a tape volume to 
create a backup copy of the data set. If the unload operation is successful, the 
partitioned data set is subsequently to be compressed in place. 
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The example follows: 


//SAVE JOB 123456, 'name',MSGLEVEL=( 1,1 ) 

Jf STEP | EXEC PGM=1LEBCOPY 

//SYSPRINT DD SYSOUT=A 

//INPDS DD DSNAME=PARTPDS , UNIT=2314,DISP=OLD, 


// \VOL=SER=PCPO0O1 
//BACKUP DD  DSNAME=SAVDATA,UNIT=2400,VOL=SER=TAPEO3, 
// DISP=(NEW,KEEP ),LABEL=(,SL) 
//SYSUT3 DD  DSNAME=TEMP1, UNIT=2314,VOL=SER=111111, 
// DISP=(NEW, DELETE ),SPACE=(80,(60,45) ) 
//SYSIN DD * 
COPY OUTDD=BACKUP, INDD=INPDS 

/* 
//STEP2 EXEC PGM=IEBCOPY , COND=(0,NE),PARM='SIZE=99999999K' 
//SYSPRINT DD  SYSOUT=A 
//COMPDS DD  DSNAME=PARTPDS, UNIT=2314,DISP=OLD, 
// VOL=SER=PCP001 | 
//SYSUT3. DD  DSNAME=TEMPA, UNIT=2314,VOL=SER=111111, 
// DISP=(NEW, DELETE ),SPACE=(80,(60,45)) 
//SYSUT4 DD  DSNAME=TEMPB, UNIT=2314,VOL=SER=111111, 
// DISP=( NEW, DELETE ),SPACE=(256,(15,1)), 
// DCB=KEYLEN=8 
//SYSIN DD * 

COPY OUTDD=COMPDS, INDD=COMPDS 


/* 
The control statements are discussed below: 


¢ INPDS DD defines a partitioned data set (PARTPDS), which resides on a 
2314 volume. The data set contains 700 members; the number of members is 
used to calculate the space to be allocated for the SYSUT3 data set. 


« BACKUP DD defines a sequential data set to which PARTPDS is to be 
unloaded. This data set must be new; the tape can be unlabeled or standard 
labeled. 


e The first SYSUT3 DD statement defines a temporary spill data set on a 2314 
volume. 


e The first SYSIN DD statement defines the control data set for the first job 
step. The data set contains a COPY statement. 


e The first COPY statement indicates the start of an unload operation because 
INDD refers to INPDS DD, which defines a partitioned data set, and OUTDD 
refers to BACKUP DD, which defines a sequential data set. Because of the 
absence of an EXCLUDE or SELECT statement, the entire data set is 
unloaded. 


e The second EXEC statement specifies in the COND parameter that this job 
step (a compress-in-place) is to be executed only if the first job step (unload) 
was successful. The PARM parameter specifies the largest possible buffer size. 


e COMPDS DD defines a partitioned data set (PARTPDS), which resides on a 
2314 volume. This data set contains 700 members. 


e The second SYSUT3 DD statement defines a temporary spill data set on a 
2314 volume for the second job step. 


e SYSUT4 DD defines a temporary spill data set on a 2314 volume. Note that 
SYSUT4 is specified for the load operation, but was not specified for the 
unload operation in the first job step. 


e The second SYSIN DD statement defines the control data set, which follows 
in the input stream, for the second job step. The data set contains a COPY 
statement. 


J 


C 
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¢« COPY specifies a compress-in-place operation because INDD and OUTDD 
both refer to COMPDS DD, which defines a partitioned data set. 


In this example, members are to be selected, excluded, unloaded, loaded, and 
copied. Processing will occur, as follows: (1) unload, excluding members, (2) 
unload, selecting members, and (3) load and copy to merge members. 


The example follows: 


//COPY JOB O06#990,'name',MSGLEVEL=( 1,1) 

//STEP EXEC PGM=IEBCOPY 

//SYSPRINT DD SYSOUT=A 

//PDS1 DD DSNAME=ACCOUNTA, UNIT=3330, VOL=SER=3330, 
J DISP=0LD 

//PDS2 DD DSNAME=ACCOUNTB, UNIT=3330, VOL=SER=3330, 
// DISP=OLD 

//SEQ1 DD DSNAME=SAVAC,UNIT=3330,VOL=SER=3330, 

// DISP=(NEW, KEEP ), SPACE=(CYL,(5,2)) 

//SEQ2 DD DSNAME=SAVACB,UNIT=2400, VOL=SER=T01911, 
// DISP=(NEW, KEEP ),LABEL=( ,SL) 

/ /NEWUP DD DSNAME=NEWACC,UNIT=2400,VOL=SER=T01219, 
// DISP=OLD,LABEL=( ,SL) 

/ /MERGE DD DSNAMF=ACCUPDAT, UNIT=2314, VOL=SER=231400, 


// DISP=OLD 
J /SYSOULS DD DSNAME=TEMP1, VOL=SER=666666, UNIT=2314, 
// DISP=(NEW,DELETE ),SPACE=( 80,(1,1)) 
//SYSUT4 DD DSNAME=TEMP2 , VOL=SER=666666, UNIT=2314, 
77 DISP=UNEW ;DELETE:),;SPACE=( 2569( 14-1) 0, 
// DCB=( KEYLEN=8 ) 
JI SYSIN DD * 
COPY OUTDD=SEQ1,INDD=PDS1 
EXCLUDE MEMBER=(D,C) 
COPY OUTDD=SEQ2, INDD=PDS2 
SELECT MEMBER=(A,K) 
COPY OUTDD=MERGE, INDD=( (NEWUP,R),PDS1,PDS2 ) 
EXCLUDE MEMBER=A 
/* 


The control statements are discussed below: 


e PDS1 DD defines a partitioned data set that contains six members (A, B, C, 
D, E, and F) and resides on a 3330 volume. 


e PDS2 DD defines a partitioned data set that contains three members (A, K, 
and L) and resides on a 3330 volume. 


e SEQ1 DD defines a new sequential data set on a 3330 volume. 
e SEQ2 DD defines a new sequential data set on a 2400 volume. 


e NEWUP DD defines an old sequential data set that is the unloaded form of a 
partitioned data set that contains eight members (A, B, C, D, M, N, O, and P). 
It resides on a 2400 volume. 


¢ MERGE DD defines a partitioned data set that contains six members (A, B, 
C, D, Q, and R) and resides on a 2314 volume. 


« The first COPY statement indicates the start of the first unload operation. 
(The input data set is partitioned; the output data set is sequential.) 


e The first EXCLUDE statement specifies that members D and C are to be 
excluded from the unload operation specified by the preceding COPY 
statement. 


e The second COPY statement indicates the start of the second unload 
operation. (The input data set is partitioned; the output data set is sequential.) 
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e The SELECT statement specifies that members A and K are to be included in 
the unload operation specified by the preceding COPY statement. 


e The third COPY statement indicates the start of the copy and load operations. 
The replace option is specified for the NEWUP data set; therefore, members 
in this data set replace identically named members on the output data set. The ~ 
first INDD data set is an unloaded data set that is to be loaded. The second 
and third INDD data sets are partitioned data sets that are to be copied. (The 
input data sets are sequential and partitioned; the output data set is 
partitioned.) 
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IBM-Supplied Patterns 


IEBDG is a data set utility used to provide a pattern of test data to be used as a 
programming debugging aid. (See “‘Introduction”’ for general data set utility 
information. ) 


An output data set, containing records of any format, can be created through the 
use of utility control statements, with or without input data. An optional user exit 
is provided to pass control to a user routine to monitor each output record before 
it is written. Sequential, indexed-sequential, and partitioned data sets can be used 
for input or output. 


To generate test data, the user constructs a pattern of data that he can analyze 
quickly for predictable results. Test data is generated through the use of utility 
control statements. 


When the user defines the contents of a field, he decides: 


e What type of pattern—IBM-supplied or user-supplied—he wishes to place 
initially in the defined field. 


e What action, if any, is to be performed to alter the contents of the field after 
it is selected for each output record. 


IBM supplies seven patterns: alphameric, alphabetic, zoned decimal, packed 
decimal, binary number, collating sequence, and random number. The user may 
choose one of them when he defines the contents of a field. All patterns except 
the binary and random number patterns repeat in a given field, provided that the 
defined field length is sufficient to permit repetition. For example, the alphabetic 
pattern is: 


ABCDEFGHIJKLMNOPORSTUVWXYZ ABCDEFG. . . 
Table 12 shows the IBM-supplied patterns. 


Table 12. IBM-Supplied Patterns 


Expressed in Expressed in 
Type Hexadecimal Printable Characters 
Alphameric Cl C2. sx «EO FO. FO ABG..24-Z2.0 62.9 
Alphabetic Cl -C2-5 4.0E9 ABC...Z 
Zoned Decimal! FOFO... FOFI 00...01 
Packed Decimal 0000... OOIC 

(Positive pattern) 

0000... 001ID 

(Negative pattern) Not applicable 
Binary Number 00... 01 

(Positive pattern) 

FF...FF 

(Negative pattern) Not applicable 
Collating Sequence 40... F9 be.<(+ | &!$*);4-/,% __ >?:#@’=" 

Boi ice ZO 9 

Random Number Random hexadecimal digits Not applicable 


Note: A packed-decimal or binary number is right-aligned in the defined field. 
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User-Specified Pictures 


The user can specify a starting character when defining an alphameric, 
alphabetic, or collating-sequence field. For example, a ten-byte alphabetic field 
for which ‘‘H” is specified as the starting character would appear as: 


HIJKLMNOPQ 


The same ten-byte alphabetic field with no specified starting character would 
appear as: 


ABCDEFGHIJ 


The user can specify a mathematical sign when defining a packed-decimal or 
binary field. If no sign is specified, the field is assumed to be positive. 


Instead of selecting an IBM-supplied pattern, the user can specify a picture to be 
placed in the defined field. The user can provide: 


e An EBCDIC character string. 
e A decimal number to be converted to packed decimal by JIEBDG. 
e A decimal number to be converted to binary by IEBDG. 


When the user supplies a picture, he must specify a picture length that is equal to 
or less than the specified field length. An EBCDIC picture is left aligned in a 
defined field; a decimal number that is converted to packed decimal or to binary 
is right aligned in a defined field. 


The user can initially load (fill) a defined field with either an EBCDIC character 
or a hexadecimal digit. For example, the 10-byte picture ““‘BADCFEHGIJI” is to 
be placed in a 15-byte field. An EBCDIC ‘‘2” is to be used to pad the field. The 
result is BADCFEHGJI22222. (If no fill character is provided, the remaining 
bytes contain binary zeros.) Remember that the fill character, if specified, is 
written in each byte of the defined field prior to the inclusion of an 
IBM-supplied pattern or user-supplied picture. 


Modification of Selected Fields 
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IEBDG can be used to change the contents of a field in a specified manner. One 
of eight actions can be selected to change a field after its inclusion in each 
applicable output record. These actions are ripple, shift left, shift right, truncate 
left, truncate right, fixed, roll, and wave. 


Figure 17 shows the effects of each of the actions on a six-byte alphabetic field. 
Note that the roll and wave actions are applicable only when a user pattern Is 
supplied. In addition, the result of a ripple action depends on which type of 
pattern—IBM-supplied or user-supplied—is present. 


Mey 


Ripple—user- Ripple—|BM- 
supplied picture supplied format Shift left Shift right 


Wave—user- 
supplied picture 


Truncate left 


Figure 17. IEBDG Actions 


If no action is selected, or if the specified action is not compatible with the 
format, the fixed action is assumed by IEBDG. 


Input and Output 
IEBDG uses the following input: 


(_ e An input data set, which contains records that are to be used in the 
construction of an output data set or partitioned data set member. The input 
data sets are optional; that is, output records can be created entirely from 
utility control statements. 


e A control data set, which contains any number of sets of utility control 
statements. 


IEBDG produces the following output: 


e An output data set, which is the result of the IEBDG operation. One output 
data set is created by each set of utility control statements included in the job 
step. 


e A message data set, which contains informational messages, the contents of 
applicable utility control statements, and any error messages. 


Note that input and output data sets may be sequential, indexed-sequential, or 
partitioned data set members. 


BDAM is not supported. 


IEBDG produces a return code to indicate the results of program execution. The 
return codes and their meanings are: 


e OO, which indicates successful completion. 


e 04, which indicates that a user routine returned a code of 16 to IEBDG. The 
job step is terminated at the user’s request. 
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e 08, which indicates that an error occurred while processing a set of utility 
control statements. No data is generated following the error. Processing 
continues normally with the next set of utility control statements, if any. 


¢« 12, which indicates that an error occurred while processing an input or output 
data set. The job step is terminated. ) 


¢ 16, which indicates that an error occurred from which recovery is not possible. 
The job step is terminated. 


Control 


IEBDG is controlled by job control statements and utility control statements. The 
job control statements are used to execute or invoke IEBDG and define the data 
sets used and produced by IEBDG. Utility control statements are used to control 
the functions of the program and to define the contents of the output records. 


Job Control Statements 


Table 13 shows the job control statements necessary for using IEBDG. 


Table 13. IEBDG Job Control Statements 


Statement Use 
JOB Initiates the job. 
EXEC Specifies the program name (PGM=IEBDG) or, if the job control statements 


reside in a procedure library, the procedure name. Additional information 
can be specified in the EXEC statement; see ““PARM Information on the 
EXEC Statement”’ below. 


SYSPRINT DD _ Defines a sequential message data set. The data set can be written on a 
system output device, a tape volume, or a direct access volume. 


SYSIN DD Defines the control data set, which contains the utility control statements 
and, optionally, input records. The data set normally resides in the input 
Stream; however, it can be defined as a sequential data set or as a member of 
a partitioned data set. 


seqinset DD Defines an optional sequential or indexed-sequential data set used as input to 
IEBDG. The data set can reside on a tape volume or on a direct access 
volume. Any number of these statements (each having a ddname different 
from all other ddnames in the job step) can be included in the job step. Each 
DD statement is subsequently referred to by a DSD utility control statement. 


parinset DD Defines an optional input partitioned data set member residing on a direct 
access volume. Any number of these statements (each having a ddname 
different from all other ddnames in the job step) can be included in the job 
step. The “‘parinset’” DD statement is referred to by a DSD utility control 
statement. 


seqout DD Defines an output (test) sequential or indexed-sequential data set. Any 
number of “‘seqout’’ DD statements can be included per job step; however, 
only one “‘seqout’’ statement is applicable per set of utility control statements. 


parout DD Defines an optional output partitioned data set member to be created and 
placed on a direct access volume. Any number of “parout’? DD statements 
(each DD statement referring to the same or to a different data set) can be 
included per job step; however, only one “‘parout’’ statement is applicable per 
set of utility control statements. 


The SYSPRINT data set and the SYSIN data set can have any blocking factor. 
Both input and output data sets can contain fixed, variable, or undefined records. 


Refer to OS/VS Data Management Services Guide, GC26-3783, for 
information on estimating space allocations. 
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Restrictions 


The ‘‘seqinset’”” DD statement can be entered: 


//seqinset DD DSNAME=setname,UNIT=xxxx,DISP=(OLD,KEEP), 
// VOLUME=SER=xxxxxx, LABEL=(...,...), 
aA DCB(applicable subparameters) 


The LABEL parameter is included only for a magnetic tape volume. If the input 
data set has an indexed-sequential organization, DSORG=IS should be coded in 
the DCB parameter. 


The “‘parinset’’ DD statement can be entered: 


//parinset DD DSNAME=setname(membername), UNIT =xxxx, DISP=(OLD, 
jf KEEP), VOLUME=SER=xxxxxx, 
Tf DCB=(applicable subparameters) 


The ‘‘seqout’’? DD statement can be entered: 


//seqout DD DSNAME=ssetname, UNIT=xxxx, 
T/ DISP=(,KEEP), VOLUME=SER=xxxxxx, 
77 DCB=(applicable subparameters) 


The LABEL parameter is included for magnetic tape; the SPACE parameter is 
included for direct access. 


The ‘‘parout’”” DD statement can be entered: 


//parout DD DSNAME=ssetname(membername), UNIT =xxxx, 


/} DISP=(,KEEP), VOLUME=SER =xxxxxx, DCB=(applicable 
ae subparameters), 
// SPACE=(applicable subparameter) 


The SPACE parameter is included on the parout DD statement when creating 
the first member to be placed in a partitioned data set. 


e The DSORG subparameter must be included in the DCB subparameters if the 
input or output data set has an indexed-sequential organization (DSORG=IS). 
If members of a partitioned data set are used, DOORG=PO or DSORG=PS 
may be coded. If the DSORG subparameter is not coded, DSORG=PS is 
assumed. 


e If the SYSPRINT DD statement is omitted, no messages are written. 


e For an indexed-sequential data set, the key length must be specified in the 
DCB. 


PARM Information on the EXEC Statement 


The EXEC statement can include an optional PARM parameter to specify the 
number of lines to be printed between headings in the message data set, coded as 
follows: 


PARM=LINECT=nnnn 


The nnnn is a four-digit decimal number that specifies the number of lines (0000 
to 9999) to be printed per page of output listing. 


If PARM is omitted, 58 lines are printed between headings (unless a channel 12 
punch is encountered in the carriage control tape, in which case a skip to channel 
1 is performed and a heading is printed). 
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Note: If IEBDG is invoked, the line-count option can be passed in a parameter 
list that is referred to by a subparameter of the LINK or ATTACH macro 
instruction. In addition, a page count can be passed in a six-byte parameter list 
that is referred to by a subparameter of the LINK or ATTACH macro instruction. 
For a discussion of linkage conventions, refer to ““Appendix B: Invoking Utility 
Programs from a Problem Program.” 


Utility Control Statements 
IEBDG is controlled by the following utility control statements: 
¢« DSD statement, which specifies the ddnames of the input and output data sets. 


One DSD statement must be included for each ser of utility control 
statements. 


¢« FD statement, which defines the contents and lengths of fields to be used in 
creating output records. 


e CREATE statement, which defines the contents of output records. 


¢ REPEAT statement, which specifies the number of times a CREATE 
statement or a group of CREATE statements are to be used in generating 
output records. 


e END statement, which marks the end of a set of IEBDG utility control 
statements. 


Any number of sets of control statements can appear in a single job step. Each 
set defines one data set. 


DSD Statement 


The DSD statement marks the beginning of a set of utility control statements and 

specifies the data sets that JIEBDG is to use as input. The DSD statement can be 

used to specify one output data set and any number of input data sets for each -) 
application of IEBDG. 


The format of the DSD statement is: 


where: 


OUTPUT=( ddname ) 
specifies the ddname of the DD statement defining the output data set. 


INPUT=( ddname.,...) 
specifies the ddname of a DD statement defining a data set used as input to 
the program. Any number of data sets can be included as input—that is, any 
number of ddnames referring to corresponding DD statements can be coded. 
Whenever ddnames are included on a continuation card, they must begin in 
column four. 


Note: The ddname SYSIN must not be coded in the INPUT parameter. Each 
parameter should appear no more than once on any DSD statement. 


FD Statement 


The FD statement defines the contents and length of a field that will be used 
subsequently by a CREATE statement (or statements) to form output records. A 
defined field within the input logical record may be selected for use in the output 
records if it is referred to, by name, by a subsequent CREATE statement. 
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Figure 18 shows how fields defined in FD statements are placed in buffer areas 
so that subsequent CREATE statements can assign selected fields to specific 
Output records. 


FD Statements—define fields 


Defines field 5 
efines field 4 


Defines field 3 
Defines field 2 = 


D 


Defines field 1 


Contents are placed in buffers oe ‘ 

so that subsequent CREATE . ; : 
statements can selectively i Field 1 Field 2 Field 3 Field 4 Field 5 
create Output records. . : 


CREATE Statement—creates output record from selected fields 


Output record 


Field 1 Field 4 


Figure 18. Defining and Selecting Fields for Output Records Using IEBDG 


Figure 19 shows how the FD statement is used to specify a field in an input 
record to be used in output records. The left-hand side of the figure shows that a 
field in the input record beginning at byte 50 is selected for use in the output 
record. The right-hand side of the figure shows that the field is to be placed at 
byte 20 in the output record. 
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Figure 19. Field Selected from the Input Record for Use in the Output Record 
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The format of the FD statement is: 


where: 
NAME= name 
specifies the name of the field defined by this FD statement. 


LENGTH length-in-bytes 
specifies the length in bytes of the defined field. For variable records, four 
bytes of length descriptor are added. 


STARTLOC= starting-byte-location 
specifies a starting location (within all output records using this field) in which 
a field is to begin. For example, if the first byte of an output record is chosen 
as the starting location, the keyword is coded STARTLOC=1; if the tenth 
byte is chosen, STARTLOC=10 is coded, etc. If STARTLOC is omitted, the 
field will begin in the first available byte of the output record (determined by 
the order of specified field names in the applicable CREATE statement). For 
variable records the starting location is the first byte after the length 
descriptor. 


FILL= 
specifies an EBCDIC character or hexadecimal digits to be placed in each byte 
ofthe defined field prior to any other operation in the construction of a field. 
If FILL is omitted, binary zeros are placed in the field. These values can be 
coded: 


‘character’ 
specifies an EBCDIC character to be placed in the defined field. 


X° 2-hexadecimal-digits’ 
specifies two hexadecimal digits (for example, FILL=X‘40’ or 
FILL=X‘FF’) to be placed in each byte of the defined field. 


FORMAT= 
specifies an IBM-supplied pattern that is to be placed in the defined field. 
FORMAT must not be used when PICTURE is used. The values that can be 
coded are: 


pattern 
specifies the IBM-supplied patterns, as follows: 


AN 
specifies an alphameric pattern. 


108 OS/VS Utilities 


ZD 
specifies a zoned-decimal pattern. 


PD 
specifies a packed-decimal pattern. 


CO 
specifies a collating sequence pattern. 


BI 
specifies a binary pattern. 


AL 
specifies an alphabetic pattern. 


RA 
specifies a random binary pattern. 


CHARACTERE character 
specifies the starting character of a field. If CHARACTER is omitted, the 
Starting character is as described under “‘IBM-Supplied Patterns”’ earlier. 


PICTURE= 
specifies the length and contents of a-_user-supplied field picture. PICTURE 
must not be used when FORMAT is used. These values can be coded: 


length 
specifies the number of characters in the FD picture. 


‘ character-string’ 
specifies an EBCDIC character string that is to be placed in the defined 
field. The character string is left aligned in the field. A character string may 
be broken in column 71 and must be continued in column 4. Double 
quotation marks must not be coded to represent a single quotation mark 
within a character string.) 


P* decimal-number’” 
specifies a decimal number that is to be converted to packed decimal and 
right-aligned in the defined field. 


B‘ decimal-number’ 
specifies a decimal number that is to be converted to binary and 
right-aligned in the defined field. In all cases, the number of characters 
within the quotation marks must equal the number specified in the length 
subparameter. 


SIGN= sign 
specifies a mathematical sign (+ or -), which is used when defining a 
packed-decimal or binary field. If SIGN is omitted, the sign is assumed to be 
positive. 


ACTIONE= action 
specifies that the contents of a defined field are to be altered after the field’s 
inclusion in an output record. These values can be coded: 


SL 
specifies that the contents of a defined field are to be shifted left after the 
field’s inclusion in an output record. 


SR 
specifies that the contents of a defined field are to be shifted right after the 
field’s inclusion in an output record. 
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Th 
specifies that the contents of a defined field are to be truncated left after 
the field’s inclusion in an output record. 


TR 
specifies that the contents of a defined field are to be truncated right after 
the field’s inclusion in an output record. 


RO 
specifies that the contents of a defined field are to be rolled after the field’s 
inclusionin an output record. RO can be used only for a user-defined field. 


WV 
specifies that the contents of a defined field are to be waved after the 
field’s inclusion in an output record. WV can be used only for a 
user-defined field. 


FX 
specifies that the contents of a defined field are to be fixed after the field’s 
inclusionin an output record. If ACTION is omitted, FX is assumed. 


RP 
specifies that the contents of a defined field are to be rippled after the 
field’s inclusion in an output record. 


INDEX= number 
specifies a number to be added to this field whenever a specified number of 
records have been written. If INDEX is omitted, no indexing is performed. 
These additional values can be coded: 


CYCLE= number 
specifies a number of output records (to be written as output or made 
available to an exit routine) that are treated as a group by the INDEX 
keyword. Whenever this field has been used in the construction of the 
specified number of records, it is modified as specified in the INDEX 
parameter. For example, if CYCLE=3 is coded, output records might 
appear as 111 222 333 444 etc. This parameter can be coded only when 
INDEX is coded. If CYCLE is omitted and INDEX is coded, a CYCLE 
value of 1 is assumed; that is, the field is indexed after each inclusion in a 
potential output record. 


RANGE= number 
specifies an absolute value which the contents of this field can never 
exceed. If an index operation attempts to exceed the specified absolute 
value, the contents of the field as of the previous index operation are used. 


INPUT= ddname 
specifies the ddname for the input data set. 


FROMLOC= number 
specifies the location of the selected field within the input logical record. The 
number represents the position in the input record. If, for example, 
FROMLOC=10 is coded, the specified field begins at the end of the tenth 
byte; if FROMLOC=1 is coded, the specified field begins at the end of the 
first byte. (For variable records, significant data begins on the first byte after 
the four-byte length descriptor.) 


Some of the FD keywords do not apply when certain patterns or pictures are 

selected by the user; for example, the INDEX, CYCLE, RANGE, and SIGN 

parameters are used only with numeric fields. Figure 20 shows which IEBDG 

keywords can be used with the applicable pattern or picture chosen by the user. 

Each keyword should appear no more than once on any FD statement. wil 


110 OS/VS Utilities 


CREATE Statement 


FORMAT/PICTURE Compatible Operations 


Action 


*Zoned decimal numbers (ZD) do not include a sign. 


Figure 20. Compatible IEBDG Operations 


The CREATE statement defines the contents of a record (or records) to be 
made available to a user routine or to be written directly as an output record (or 
records). 


The format of the CREATE statement is: 


where: 


QUANTITY = number 

specifies the number of records that this CREATE statement is to generate; 
each record is specified by the other parameters. If QUANTITY is omitted and 
INPUT is not specified, only one output record is created. If QUANTITY is 
omitted and INPUT is specified, the number of records created is equal to the 
number of records in the input data set. If both QUANTITY and INPUT are 
coded, and the quantity specified is greater than the number of records in the 
input data set, the number of records created is equal to the number of input 
records to be processed plus the generated data up to the specified number. 
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FILL= 
specifies a value that is to be placed in each byte of the output record before 
any other operation in the construction of record. If FILL is not coded, binary 
zeros are placed in the output record. These values can be coded: 


‘ character’ 
specifies an EBCDIC character that is to be placed in each byte of the 
output record. 


X° 2-hexadecimal-digits’ 
specifies two hexadecimal digits (for example, FILL=X‘40’, or 
FILL=X‘FF’) to be placed in each byte of the output record. 


INPUT= 
defines an input data set whose records are to be used in the construction of 
output records. If INPUT is not coded, the output records are created entirely 
from utility control statements. If INPUT is coded, QUANTITY should also be 
coded, unless the remainder of the input records are all to be processed by 
this CREATE statement. These values can be coded: 


ddname 
specifies the ddname of a DD statement defining an input data set. 


SYSIN[(cccc )| 
specifies that the SYSIN data set (input stream) contains records (other 
than utility control statements) to be used in the construction of output 
records. If SYSIN is coded, the input records follow this CREATE 
statement (unless the CREATE statement is in a REPEAT group, in which 
case the input records follow the last CREATE statement of the group). 
When INPUT=SYSIN with no cccc value is coded, the input records are 
delimited from any additional utility control statements by a record 
containing $$$E in columns 1 through 4. If this value is coded, the input 
records are delimited by a record containing EBCDIC characters beginning 
in column 1; the cccc can be any combination of from one to four 
EBCDIC characters. 


PICTURE= 
specifies the length, starting byte, and contents of a user-supplied picture 
(CREATE statement picture). If both PICTURE and NAME are omitted, the 
fill character specified in the CREATE statement appears in each byte of 
applicable output records. These values can be coded: 


length 
specifies the number of bytes that the picture will occupy. 


startloc 
specifies a starting byte (within any applicable output record) in which the 
picture is to begin. 


* character-string’ 
specifies an EBCDIC character string that is to be placed in the applicable 
record(s). The character string is left aligned at the defined starting byte. A 
character string may be broken in column 71 and continued in column 4. 


P* decimal-number’ 
specifies a decimal number that is to be converted to packed decimal and 
right-aligned (within the boundaries of the defined length and starting byte) 
in the output records. 
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B‘ decimal-number’ 
specifies a decimal number that is to be converted to binary and 
right-aligned (within the boundaries of the defined length and starting byte) 
in the output records. 


NAME= 
specifies the name or names of previously defined fields to be included in the 
applicable output records. If both NAME and PICTURE are omitted, the fill 
character specified in the CREATE statement appears in each byte of the 
applicable output record. These values can be coded: 


(name ,...) 
specifies the name or names of a field or fields to be included in the 
applicable output record(s). Each field is included in an output record in 
the order in which its name is encountered in the CREATE statement. 


COPY= number 
indicates that all fields named in the inner parentheses (maximum of 
twenty) are to be treated as a group and included the specified number of 
times in each output record produced by this CREATE statement. Any 
number of sets of inner parentheses can be included with NAME; however, 
sets of parentheses cannot be embedded. Within each set of inner 
parentheses, COPY must appear before the name of any field. 


EXIT= routinename 
specifies the name of a user routine that is to receive control from IEBDG 
before writing each output record. 


After processing each potential output record, the user routine provides a return 
code to instruct IEBDG how to handle the output record. The user codes are: 


e 00, which specifies that the record is to be written. 


e 04, which specifies that the record is not to be written. The skipped record is 
not to be counted as a generated output record; processing is to continue as 
though a record were written. If skips are requested through user exits and 
input records are supplied, each skip causes an additional input record to be 
processed in the generation of output records. For example, if a CREATE 
statement specifies that ten output records are to be generated and a user exit 
indicates that two records are to be skipped, 12 input records are processed. 


e« 12, which specifies that the processing of the remainder of this set of utility 
control statements is to be bypassed. Processing is to continue with the next 
DSD statement. 


¢ 16, which specifies that all processing is to halt. 


Note: When an exit routine is loaded and when the user returns control to 
IEBDG, register one contains the address of the first byte of the output record. 
Each keyword should appear no more than once on any CREATE statement. 


Figure 21 shows the addition of field X to two different records. In record 1, 
field X is the first field referred to by the CREATE statement; therefore, field X 
begins in the first byte of the output record. In record 2, two fields, field A and 
field B, have already been referred to by a CREATE statement; field X, the next 
field referred to, begins immediately after field B. Field X does not have a 
special starting location in this example. 
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Field X 
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Figure 21. Default Placement of Fields Within an Output Record Using IEBDG 


The user can also indicate that a numerical field is to be modified after it has 
been referred to n times by a CREATE Statement or statements, that is, after 
n cycles, a modification is to be made. A modification will add a user-specified 
number to a field. 


The CREATE statement constructs an output record by referring to previously 
defined fields by name and/or by providing a picture to be placed in the record. 
The user can generate multiple records with a single CREATE statement. 


When defining a picture in a CREATE statement, the user must specify its 
length and starting location in the output record. The specified length must be 
equal to the number of specified EBCDIC or numeric characters. (When a 
specified decimal number is converted to packed decimal or binary, it is 
automatically right aligned.) 


Figure 22 shows three ways in which output records can be created from utility 
control statements. 


1. Fields only Output record 


Previously defined 
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2. Fields and 
picture 


3. Picture only 


Output record 


Figure 22. Creating Output Records with Utility Control 


As an alternative to creating output records from utility control statements alone, 
the user can provide input records, which can be modified and written as output 
records. Input records can be provided directly in the input stream, or in a data 
set. 


As previously mentioned, the CREATE statement is responsible for the 
construction of an output record. An output record is constructed in the 
following order: 


1. A fill character, specified or default (binary zero), is initially loaded into each 
byte of the output record. 


2. An input record, if any is provided, is left aligned in the output record. 


3. FD fields, if any, are placed in the output record in the order of the 
appearance of their names in the CREATE statement. 


4. A CREATE statement picture, if any, is placed in the output record. 


IEBDG provides a user exit so that the user can provide his own routine to 
analyze or further modify a newly constructed record before it is placed in the 
output data set. 


A set of utility control statements contains one DSD statement, any number of 
FD, CREATE, and REPEAT statements, and one END statement when the 
INPUT parameter is omitted from the FD card. 


When selecting fields from an input record (FD INPUT=ddname), the field must 
be defined by an FD statement within each set of utility control statements. In 
this case, defined fields for field selection are not usable across sets of utility 
control statements. The FD card may be duplicated and used in more than one 
set of utility control statements within the job step. 


REPEAT Statement 


The REPEAT statement specifies the number of times a CREATE statement or 
group of CREATE statements is to be used repetitively in the generation of 
output records. The REPEAT statement precedes the CREATE statements to 
which it applies. 


Figure 23 shows a group of five CREATE statements repeated n times. 


saat 


Figure 23. Repetition Due to the REPEAT Statement Using IEBDG 
The format of the REPEAT statement is: 

| label] REPEAT QUANTITY= number [,CREATE= number | 
where: 


QUANTITY = number 
specifies the number of times the defined group of CREATE statements is to 
be used repetitively. This number cannot exceed 65,535. 
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END Statement 


IEBDG Examples 


IEBDG Example 1 
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CREATE= number 
specifies the number of following CREATE statements to be included in the 
group. If the CREATE parameter is omitted, only one CREATE statement is 
repeated. 


The END statement is used to mark the end of a set of utility control statements. 
Each set of control statements can pertain to any number of input data sets and 
a single output data set. 


The format of the beth statement iS: 
_ A Biace ie nt ‘a. ie . LF Ae Foe a re Te, oh ay 

pre er ey yt Pe ea ah higtte RA Ah Ribs ee Nes dee Ste ae a 

[abel END we ie ie : i RCE g ee Cees Gl ee aka “Ng 


eae 4 ’ se ; ’ wa > f ; fats 


The following examples illustrate some of the uses of IEBDG. Table 14 can be 
used as a quick reference guide to IEBDG examples. The numbers in the 
‘Example’ column point to examples that follow. 


Table 14. IEBDG Example Directory 


Data Set 
Operation Organization Device Comments Example 
Place binary zeros in Sequential 9-track tape Blocked input and 
selected fields. output. l 
Ripple alphabetic Sequential 9-track tape, Blocked input and 
pattern 2314 Disk output. 2 
Create output records Sequential 2314 Disk Blocked output. 3 
from utility control 
Statements 
Modify records from Partitioned, 2314 Disk Reblocking is performed. 
partitioned members Sequential Each block of output 
and input stream records contains ten 
modified partitioned 
input records and two 
input stream records. 4 
Create partitioned Partitioned 2314 Disk Blocked output. One set 
members for utility of utility control 
control statements statements per member. 5 
Roll and wave user- Sequential 2314 Disk Output records are 
supplied patterns created from utility 
control statements. 6 
Create indexed- Sequential, 2314 Disk Output records are 
sequential data set Indexed- created by augmenting 
using field selection sequential selected input fields 
and data generation with generated data. 7 


In this example, binary zeros are to be placed in two fields of records copied 
from a sequential data set. After the operation, each record in the copied data set 
(OUTSET) contains binary zeros in locations 20 through 29 and 50 through 59. 


IEBDG Example 2 


The example follows: 


72 
//CLEAROUT JOB ,,MSGLEVEL=1 
Aj EXEC PGM=IEBDG 
//SYSPRINT DD SYSOUT=A 
//SEQIN DD DSNAME=INSET,UNIT=2400,DISP=(OLD,KEEP), 
// DCB=( RECFM=FB, LRECL=80, BLKSIZE=800 ), 
// VOLUME=SER=240000, LABEL=( ,NL) 
//SEQOUT DD  DSNAME=OUTSET, UNIT=2400, VOLUME=SER=240001, 
// DCB=( RECFM=FB, LRECL=80, BLKSIZE=800 ), 
// DISP=( ,KEEP),LABEL=( ,NL) 
//SYSIN DD * 
DSD OUTPUT=( SEQOUT ), INPUT=( SEQIN) 
FD NAME=FIELD1, INPUT=SEQIN, LENGTH=80 
FD NAME=FIELD2, LENGTH=10, STARTLOC=20 
FD NAME=FIELD3, LENGTH=10, STARTLOC=50 
CREATE QUANTITY=100, INPUT=SEQIN, NAME=(FIELD1,FIELD2 4\\c 
FIELD3 ) 
END 
/* 


The control statements are discussed below: 


e SEQIN DD defines a sequential input data set (INSET). The data set was 
originally written on a 9-track, unlabeled tape volume. 


¢ SEQOUT DD defines the test data set (OUTSET). The output records are 
identical to the input records, except for locations 20 through 29 and 50 
through 59, which contain binary zeros at the completion of the operation. 


e SYSIN DD defines the control data set, which follows in the input stream. 


e DSD marks the beginning of a set of utility control statements and refers to 
the DD statements defining the input and output data sets. 


e The first FD statement defines an 80-byte field of input data. 


¢ The second and third FD statements create two ten-byte fields (FIELD2 and 
FIELD3) that contain binary zeros. The fields are to begin in the 20th and 
50th bytes of each output record. 


¢ CREATE constructs 100 output rcords in which the contents of previously 
defined fields (FIELD1, FIELD2, and FIELD3) are placed in their respective 
starting locations in each of the output records. Input records from data set 
INSET are used as the basis of the output records. 


e END signals the end of a set of utility control statements. 


In this example, a ten-byte alphabetic pattern is to be rippled. At the end of the 
job step the first output record contains ““ABCDEFGHIJ”’, followed by data in 
location 11 ‘through 80 from the input record; the second record contains 
“BCDEFGHIJK” followed by data in locations 11 through 80, etc. 
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IEBDG Example 3 
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The example follows: 


72 
//RIPPLE JOB’ ,,MSGLEVEL=1 
Ja, EXEC PGM=IEBDG 
//SYSPRINT DD  SYSOUT=A 
//SEQIN DD DSNAME=INSET,DISP=(OLD,KEEP ), VOL=SER=240000, 
// DCB=(RECFM=FB, LRECL=80, BLKSIZE=800 ), UNIT=2400 
//SEQOUT DD  DSNAME=OUTSET,UNIT=2314,VOLUME=SER=231400, 
// DCB=( RECFM=FB,LRECL=80,BLKSIZE=800 ), 
J DUSP=(s KEEP )SPACE=( TREK 10,110) 
//SYSIN DD * 
DSD OUTPUT=( SEQOUT ), INPUT=( SEQIN ) 
FD NAME=FIELD1, INPUT=SEQIN, LENGTH=80 
FD NAME=FIELD2,LENGTH=10, FORMAT=AL, ACTION=RP, (Ac 
STARTLOC=1 
CREATE  QUANTITY=100, INPUT=SEQIN,NAME=( FIELD1,FIELD2 ) 
END 
/¥* 


The control statements are discussed below: 


e SEQIN DD defines an input sequential data set (INSET). The data set was 
Originally written on a 9-track, standard-labeled tape volume. 


e SEQOUT DD defines the test output data set (OUTSET). Twenty tracks of 
primary space and ten tracks of secondary space are allocated for the 
sequential data set on a 2314 volume. 


e SYSIN DD defines the control data set, which follows in the input stream. 


e DSD marks the beginning of a set of utility control statements and refers to 
the DD statements defining the input and output data sets. 


e The first FD statement defines an 80-byte field of input data. 


e The second FD statement creates a ten-byte field in which the pattern | | 
ABCDEFGHIJ is placed. The data is rippled after each output record is 
written. 


e CREATE constructs 100 output records in which the contents of a previously 
defined field (FIELD1) are included. The CREATE statement uses input 
records from data set INSET as the basis of the output records. 


¢« END signals the end of a set of utility control statements. 


In this example, output records are to be created entirely from utility control 
statements. Three fields are to be created and used in the construction of the 
output records. In two of the fields, alphabetic data is to be truncated; the other 
field is a numeric field that is to be incremented (indexed) by one after each 
output record is written. Figure 24 shows the contents of the output records at 
the end of the job step. 


Field 3 (packed decimal) 
61 71 80 


1 
[ABCDEF GHIIKLMNOPORSTUVWXYZABCD | ABCDEFGHIJKLMNOPGRSTUVWXYZABCD| FF... FF [123.90 
/ DEF GHIJKEMNOPORSTUVWXYZABCD| ABCDEFGHIJKLMINOPGRSTUVWXYZA [FF FF [123.93 | 


Field 1 


Figure 24. Output Records at Job Step Completion 


The example follows: 


//UTLYONLY JOB ,,MSGLEVEL=1 
Tf EXEC PGM=IEBDG 
//SYSPRINT DD SYSOUT=A 
//SEQOUT DD  DSNAME=OUTSET,UNIT=2314,DISP=(,KEEP), 
// DCB=(RECFM=FB, LRECL=80, BLKSIZE=800 ), 
// SPACE=( TRK,(10,10)),VOLUME=SER=240000 
//SYSIN DD DATA 
DSD OUTPUT=( SEQOUT ) 
FD NAME=FIELD1,LENGTH=30,STARTLOC=1,FORMAT=AL,ACTION=TL 
FD NAME=FIELD2,LENGTH=30,STARTLOC=31,FORMAT=AL, ACTION=TR 
FD NAME=FIELD3,LENGTH=10,STARTLOC=71, (Sc 
PICTURE=10,P'1234567890', INDEX=1 
CREATE QUANTITY=100,NAME=(FIELD1,FIELD2,FIELD3 ),FILL=X'FF' 
END 
/* 
The control statements are discussed below: 


¢ SEQOUT DD defines the test output data set. Ten tracks of primary space 
and ten tracks of secondary space are allocated for the sequential data set on 
a 2314 volume. 


e SYSIN DD defines the control data set, which follows in the input stream. 


e DSD marks the beginning of a set of utility control statements and refers to 
the DD statement defining the output data set. 


e FD defines the contents of three fields to be used in the construction of 
output records. The first field contains 30 bytes of alphabetic data to be 
truncated left after each output record is written. The second field contains 30 
bytes of alphabetic data to be truncated right after each output record is 
written. The third field is a ten-byte field containing a packed-decimal number 
(1234567890) to be incremented by one after each record is written. 


e CREATE constructs 100 output records in which the contents of previously 
defined fields (FIELD1, FIELD2, and FIELD3) are included. 


e END signals the end of a set of utility control statements. 


IEBDG Example 4 


In this example, two partitioned members and input records from the input 
stream are to be used as the basis of a partitioned output member. Each block of 
12 output records is to contain ten modified records from an input partitioned 
member and two records from the input stream. Figure 25 shows the content of 
the output partitioned member at the end of the job step. 
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Input Output Records 


Figure 25. Output Partitioned Member at Job Step Completion 


The example follows: 


//MIX JOB ,,MSGLEVEL=1 

7 EXEC PGM=LEBDG 

//SYSPRINT DD SYSOUT=A 

//PARIN1 DD DSNAME=INSET 1( MEMBA ), UNIT=2314,DISP=OLD, 


// DCB=( RECFM=FB,LRECL=80, BLKSIZE=800,DSORG=PS ), 

// VOLUME=SER=231400 

//PARIN2 DD  DSNAME=INSET2( MEMBA ),UNIT=2314,DISP=OLD, 

// DCB( RECFM=FB, LRECL=80, BLKSIZE=960,DSORG=PS ), 

// VOLUME=SER=231401 

//PAROUT DD  DSNAME=PARSET( MEMBA ), UNIT=2314,DISP=( ,KEEP), 
// VOLUME=SER=231402,SPACE=(TRK,(10,10,5)), 

// DCB( RECFM=FB, LRECL=80, BLKSIZE=960 ; DSORG=PS ) 


77 SISIN DD DATA 
DSD OUTPUT=( PAROUT ), INPUT=( PARIN1, PARIN2 ) 
FD NAME=FTIELD1, LENGTH=13,PICTURE=13,'DEPARTMENT 21' 


REPEAT QUANTITY=10, CREATE=2 
CREATE QUANTITY=10, INPUT=PARIN1,NAME=FIELD1 
CREATE QUANTITY=2, INPUT=SYSIN 


(input records | through 20) 


$$$E 
REPEAT QUANTITY=10,CREATE=2 
CREATE QUANTITY=10, INPUT=PARIN2,NAME=FIELD1 
CREATE QUANTITY=2,INPUT=SYSIN 


(input records 21 through 40) 
$$$E 


END 
/* 
The control statements are discussed below: 
e PARIN1 DD defines one of the input partitioned members. 


e PARIN2 DD defines the second of the input partitioned members. (Note that 
the members are from different partitioned data sets.) 
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IEBDG Example 5 


e PAROUT DD defines the output partitioned member. This example assumes 
that the partitioned data set does not exist prior to the job step; that is, this 
DD statement allocates space for the partitioned data set. 


e SYSIN DD defines the control data set, which follows in the input stream. 


e DSD marks the beginning of a set of utility control statements and refers to 
the DD statements defining the input and output data sets. 


e FD creates a 13-byte field in which the picture “DEPARTMENT 21” is 
placed. 


e The first REPEAT statement indicates that the following group of two 
CREATE statements is to be repeated ten times. 


e The first CREATE statement creates ten output records. Each output record is 
constructed from an input record (from partitioned data set INSET1) and 
from previously defined FIELD1. 


e The second CREATE statement indicates that two records are to be 
constructed from input records included next in the input stream. 


¢« The $$$E record separates the input records from the REPEAT statement. 
The next REPEAT statement group is identical to the preceding group, except 
that records from a different partitioned member are used as input. 


e END signals the end of a set of utility control statements. 


In this example, output records are to be created from three sets of utility control 
statements and written in three partitioned data set members. Four fields are to 
be created and used in the construction of the output records. In two of the 
fields (FIELD1 and FIELD3), alphabetic data is to be shifted. The other two 
fields are to be fixed-alphameric and zoned-decimal fields. Figure 26 shows the 
partitioned data set members at the end of the job step. 


MEMBA 


Binary zeros 
1 31 51 71 80 


00000000070000000001 
noooooogeToconeAaAT | Fill 


MEMBB 


1 21 41 
90000000070000000001 
ABCDEFGHIJKLMNOPORS| ABCDEFGHIJKLMNOPORS |00000000010000000001 
00000000010000000001 
ABCDEFGHIJKLMNOPO noNAADGGOTOARAAANNA 


MEMBC 


Field 4 Field 1 Binary zeros 


1 31 61 
ful 


Figure 26. Partitioned Data Set Members at Job Step Completion 
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IEBDG Example 6 
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The example follows: 


J /UTSTIS JOB ,,MSGLEVEL=1 


// 


EXEC PGM=IEBDG 


f/SYSPRINT DD SYSOUT=A 

//PAROUT1 DD DSNAME=PARSET( MEMBA ), UNIT=2314,DISP=(,KEEP), 
// NVOLUME=SER=231400,SPACE=(TRK,(10,10,5)), 

// DCB=( RECFM=FB, LRECL=80, BLKSIZE=800,DSORG=PS ) 

//PAROUT2 DD DSNAME=PARSET( MEMBB ), UNIT=AFF=PAROUT1, 

// DCB=( RECFM=FB, LRECL=80, BLKSIZE=800 ,DSORG=PS ), 

// DISP=OLD , VOLUME=SER=231400 

//PAROUT3 DD DSNAME=PARSET( MEMBC ), UNIT=AFF=PAROUT1, 

// DCB=( RECFM=FB,LRECL=80,BLKSIZE=800,DSORG=PS ), 

// DISP=OLD, VOLUME=SER=231400 


//SYSIN DD DATA 
DSD OUTPUT=( PAROUT1 ) 
FD NAME=FIELD1,LENGTH=30, FORMAT=AL, ACTION=SL 
FD NAME=FIELD2, LENGTH=20 , FORMAT=ZD 
FD NAME=FIELD3 , LENGTH=20, FORMAT=AL, ACTION=SR 
FD NAME=FIELD4 , LENGTH=30 , FORMAT=AN 
CREATE  QUANTITY=4,NAME=(FIELD1,FIELD3,FIELD2 ) 
END 
DSD OUTPUT=( PAROUT2 ) 
CREATE  QUANTITY=4,NAME=( ( COPY=3,FIELD3 ),FIELD2 ) 
END 
DSD OUTPUT=( PAROUT3 ) 
CREATE  QUANTITY=4,NAME=( FIELD4,FIELD1 ) 
END 

/* 


The control statements are discussed below: 


In 


PAROUT1 DD defines the first member (MEMBA) of the partitioned output 
data set. This example assumes that the partitioned data set does not exist 
prior to this job step; that is, this DD statement allocates space for the data 
set. 


PAROUT2 and PAROUT3 DD define the second and third members, 
respectively, of the output partitioned data set. Note that each DD statement 
specifies DISP=OLD and UNIT=AFF=PAROUTI1. 


SYSIN DD defines the control data set, which follows in the input stream. 


DSD marks the beginning of a set of utility control statements and refers to 
the DD statement defining the member applicable to that set of utility control 
statements. 


FD defines the contents of a field that is used in the subsequent construction 
of output records. 


CREATE constructs four records from combinations of previously defined 
fields. 


END signals the end of a set of utility control statements. 


this example, ten fields containing user-supplied EBCDIC pictures are to be 


used in the construction of output records. After a record is written, each field is 
rolled or waved, as specified in the applicable FD statement. Figure 27 shows the 
contents of the output records at the end of the job step. 


J 


FIELD1 FIELD2 FIELD3 | FIELD4 FIELDS FIELD6 FIELD? FIELD8 FIELD9 | FIELD10 


CCCCC 
CCCCC 


AAAAA| BBBBB 


A 
a 


Figure 27. Contents of Output Records at Job-Step Completion 


The example follows: 


72 
//ROLLWAVE JOB ,,MSGLEVEL=1 
vy EXEC PGM=IEBDG 
//SYSPRINT DD  SYSOUT=A 
//OUTSET DD  DSNAME=SEQSET, UNIT=2314,DISP=(,KEEP), 
// JOLUME=SER=SAMP , SPACE=(TRK,(10,10)), 
// DCB=( RECFM=FB, LRECL=80, BLKSIZE=800 ) 
//SYSIN DD + 
DSD  OUTPUT=( OUTSET ) 
FD NAME=FIELD1,LENGTH=8,PICTURE=8,' AAAAA' , ACTION=RO 
FD NAME=FIELD2, LENGTH=8, PICTURE=8,'BBBBB _—'', ACTION=RO 
FD NAME=FIELD3, LENGTH=8,PICTURE=8,'A AA  ',ACTION=RO 
FD NAME=FIELD4, LENGTH=8, PICTURE=8,' BB B' , ACTION=RO 
FD NAME=FIELD5, LENGTH=8,PICTURE=8,' AAA  ',ACTION=RO 
FD NAME=FIELD6, LENGTH=8, PICTURE=8,' | CCCCC', ACTION=WV 
FD NAME=FIELD7, LENGTH=8,PICTURE=8,' DDDD ',ACTION=WV 
FD NAME=FIELD8, LENGTH=8, PICTURE=8,' C CC ',ACTION=Wwv 
FD NAME=FIELD9, LENGTH=8,PICTURE=8,' DD  D',ACTION=WV 
FD NAME=FIELD10, LENGTH=8, PICTURE=8,' CCC  ',ACTION=Wwvy 
CREATE QUANTITY=300,NAME=(FIELD1,FIELD2,FIELD3, E6 
FIELD4, FIELDS, FIELD6,FIELD7, FIELDS, y yc 


FIELD9,;FIELD10 
/* 
The control statements are discussed below: 


e OUTSET DD defines the output sequential data set on a 2314 volume. 
Twenty tracks of primary space and ten tracks of secondary space are 
allocated to the data set. 


e SYSIN DD defines the control data set, which follows in the input stream. 


e DSD marks the beginning of a set of utility control statements and refers to 
the DD statement defining the output data set. 


¢ FD defines a field to be used in the subsequent construction of output records. 
Note that the direction and frequency of the initial roll or wave depends on 
the location of data in the field. 


¢ CREATE constructs 300 records from the contents of the previously defined 
fields. 


e END signals the end of a set of utility control statements. 
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IEBDG Example 7 
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In this example, the first ten bytes of the output record contain data generated in 
zoned-decimal format. This field serves as the key field for the output record in 
the output indexed-sequential data set. The key field is incremented (indexed) by 
one for each record. The input sequential data set provides an additional 80-byte 
field to complete the output record. 


The example follows: 


Pe 
//CREATEIS JOB MSGLEVEL=1 
//BEGIN EXEC PGM=IEBDG 
//TAPEIN DD  DCB=(BLKSIZE=80, LRECL=80,RECFM=F ), 
// DISP=( OLD, KEEP ), UNIT=2400, LABEL=(,SL), 
// DSNAME=TAPEIT, VOL=SER=MASTER 
//DISKOUT DD  DCB=( BLKSIZE=270,LRECL=90,RECFM=FB, 
// DSORG=IS,NTM=2,OPTCD=MY , RKP=0,KEYLEN=10, 
// CYLOFL=1 ),UNIT=2314,SPACE=(CYL,1), 
// VOL=SER=231400, DSNAME=CREATIS , DISP=( NEW, KEEP ) 
//SYSPRINT DD  SYSOUT=A 
//SYSIN DD 
DSD OUTPUT=( DISKOUT ), INPUT=( TAPEIN ) 
FD NAME=DATAFD , LENGTH=80 , FROMLOC=1, ae 
STARTLOC=11, INPUT=TAPEIN 
FD NAME=KEYFD, LENGTH=10, STARTLOC=1, FORMAT=ZD, INDEX=1 
CREATE INPUT=TAPEIN, NAME=( KEYFD,DATAED ) 
END 
/* 


The control statements are discussed below: 

¢ TAPEIN DD defines the sequential input data set. 

e DISKOUT DD defines the indexed-sequential output data set. 

¢ SYSIN DD defines the control data set, which follows in the input stream. 


e DSD marks the beginning of a set of utility control statements and refers to 
the DD statement defining the output data set. 


e FD defines a field that will be used in the subsequent construction of output 
records. The first FD statement in this example defines and locates an 80-byte 
field of input data. The data is field selected from one of the input logical 
records and placed at start location 11 of the output logical record. The 
second FD statement defines and locates the ten-byte key field. 


e CREATE constructs a 90-byte output record by referring to the previously 
defined fields. 


e END signals the end of a set of utility control statements. 


EBEDIT Program 


Input and Output 


IEBEDIT is a data set utility used to create an output data set containing a 
selection of jobs or job steps. (See “Introduction” for general data set utility 
information.) At a later time, the data set can be used as an input stream for job 
processing. 


IEBEDIT creates an output job stream by editing and selectively copying a job 
stream provided as input. The program can copy: 


e An entire job or jobs, including JOB statements and any associated JOBLIB 
Statements. 


e Selected job steps, including the JOB statement and any associated JOBLIB 
statement. 


All selected JOB statements, JOBLIB statements, jobs, or job steps are placed in 
the output data set in the same order as they exist in the input data set. Note 
that a JOBLIB statement is copied only if it follows a selected JOB statement. 


When IEBEDIT encounters a selected job step containing an input record having 
the characters “..*” in columns | through 3, the program automatically converts 

that record to a termination statement (/* statement) and places it in the output 
data set. 


IEBEDIT uses the following input: 


e An input data set, which is a sequential data set consisting of a job stream. 
The input data set is used as source data in creating an output sequential data 
set. 


¢« A control data set, which contains utility control statements that are used to 
specify the organization of jobs and job steps in the output data set. 


IEBEDIT produces the following output: 


e An output data set, which is a sequential data set consisting of a resultant job 
stream. 


¢ A message data set, which is a sequential data set that contains applicable 
control statements, error messages, if applicable, and, optionally, the output 
data set. 


IEBEDIT provides a return code to indicate the results of program execution. 
The return codes and their meanings are: 


¢ 00, which indicates successful completion. 


¢ 04, which indicates that an error occurred. The output data set may not be 
usable as a job stream. Processing continues. 


e 08, which indicates that an unrecoverable error occurred while attempting to 
process the input, output, or control data set. The job step is terminated. 
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Control 


Job Control Statements 


Restrictions 


Utility Control Statement 


EDIT Statement 
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IEBEDIT is controlled by job control statements and utility control statements. 

The job control statements are required to execute or invoke the program and i9 

define the data sets used and produced by the program. The utility control 

statements are used to control the functions of the program. J 


Table 15 shows the job control statements necessary for using IEBEDIT. 


Table 15. IEBEDIT Job Control Statements 


Statement Use 
JOB Initiates the job. 
EXEC Specifies the program name (PGM=IEBEDIT) or, if the job control statements 


reside in a procedure library, the procedure name. 


SYSPRINT DD Defines a sequential message data set. The data set can be written to a system 
Output device, a tape volume, or a direct access volume. 


SYSUT1 DD _ Defines a sequential input data set on a card reader, tape volume, or direct 
access device. 


SYSUT2 DD _ Defines a sequential output data set on a card punch, printer, tape volume, or 
direct access device. 


SYSIN DD Defines the control data set. The data set normally is included in the input 
stream; however, it can be defined as a member of a procedure library or as a 
sequential data set existing somewhere other than in the input stream. 


e The block size for the SYSPRINT data set must be a multiple of 121. The 
block size for the SYSIN, SYSUT1, and SYSUT2 data sets must be a multiple 
of 80. Any blocking factor can be specified for these block sizes. 


IEBEDIT is controlled through the EDIT utility control statement. 


The EDIT statement indicates which step or steps or a specified job in the input 
data set are to be included in the output data set. Any number of EDIT 
statements can be included in an operation, thus including selected jobs in the 
output data set. 


EDIT statements must be included in the same order as the input jobs that they 
represent. If no EDIT statement is present in the control data set, the entire 
input data set is copied. 


The format of the EDIT statement is: 


: \tets * 
5 Fe a, aay : Oe rt, 7 
te 2 ry 


na Ne . 
7 . 
ary'= 


where: 


START= jobname 
specifies the name of the input job to which the EDIT statement applies. 
(Each EDIT statement must apply to a separate job.) If START is specified 
without TYPE and STEPNAME, the JOB statement and all job steps for the 
specified job are included in the output. If START is omitted and only one 
EDIT statement is provided, the first job encountered in the input data set is 
processed. If START is omitted from an EDIT statement other than the first 
statement, processing continues with the next JOB statement found in the 
input data set. 


TYPE= 
specifies the contents of the output data set. If TYPE is omitted, 
TYPE=POSITION is assumed. These values can be coded: 


POSITION 
specifies that the output is to consist of a JOB statement, the job step 
specified in the STEPNAME parameter, and all steps that follow it. All job 
steps preceding the specified step are omitted from the operation. 


INCLUDE 
specifies that the output data set is to contain a JOB statement and all job 
steps specified in the STEPNAME parameter. 


EXCLUDE 
specifies that the output data set is to contain a JOB statement and all job 
steps belonging to the job except those steps specified in the STEPNAME 
parameter. 


STEPNAME= 
specifies the first job step to be placed in the output data set when coded with 
TYPE=POSITION. Job steps preceding this step are not copied to the output 
data set. When coded with TYPE=INCLUDE or TYPE=EXCLUDE, 
STEPNAME specifies the names of job steps that are to be included in or 
excluded from the operation. For example, 
STEPNAME=(STEPA,STEPF-STEPL,STEPZ) indicates that job steps 
STEPA, STEPF through STEPL, and STEPZ are to be included in or excluded 
from the operation. If STEPNAME is omitted, the entire input job whose 
name is specified on the EDIT statement is copied. If no job name is 
specified, the first job encountered is processed. 


NOPRINT 
specifies that the message data set is not to include a listing of the output data 
set. If NOPRINT is omitted, the resultant output is listed in the message data 
set. 


Note: Any JOBLIB DD statement that follows a selected JOB statement is 
automatically copied to the output data set. 


IEBEDIT Examples 


The following examples show some of the uses of IEBEDIT. Table 16 can be 
used as a quick reference guide to IEBEDIT examples. The numbers in the 
‘‘Example” column point to examples that follow. 
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IEBEDIT Example 1 


IEBEDIT Example 2 
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Table 16. IEBEDIT Example Directory 


Operation Devices Comments Example 
COPY 9-track tape The input data set contains three jobs. One job is 
to be copied. I 
COPY 7-track tape The output data set is the second data set on the 
volume. One job step is to be copied from each of 
three jobs. 2 
COPY 2314 Disk, Include a job step from one job and exclude a 
9-track tape job step from another job. 3 
COPY 2314 or 2319 Latter portion of a job stream is to be copied. 
Disk! 4 
COPY 9-track tape All records in the input data set are to be copied. 
The “*..*” record is converted to a /* statement in 
the output data set. 5 


' The 2319 disk is functionally equivalent to the 2314 disk; to use the 2319, specify 2314 in the 
control statement. 


In this example one job (JOBA), including all of its job steps (A, B, C, and D), 
is to be copied into the output data set. The input data set contains three jobs: 
JOBA, which has four job steps; JOBB, which has three job steps; and JOBC, 
which has two job steps. 


The example follows: 


7 EDLY) JOB O0O9#440,SMITH 
AA EXEC PGM=IEBEDIT 
//SYSPRINT DD SYSOUT=A 
fj SYSUT1 DD UNIT=2400,DISP=( OLD, KEEP ), VOLUME=SER=00 1234 
Jf SYSUTZ DD UNIT=2400 ,DISP=( NEW, KEEP ), VOLUME=SER=001235, 
// DCB=( RECFM=F, LRECL=80,BLKSIZE=80 ), 
// DSNAME=OUTTAPE 
J /SYSIN DD * 
EDIT START=JOBA 
/* 


The control statements are discussed below: 


e SYSUT1 DD defines the input data set. The data set resides on a 9-track, 
standard-labeled tape volume (001234). 


¢ SYSUT2 DD defines the output data set. The data set is to reside as the first 
data set on a standard-labeled, 9-track tape volume (001235). 


e SYSIN DD defines the control data set, which follows in the input stream. 
e EDIT indicates that JOBA is to be copied in its entirety. 


This example copies: (1) the JOB statement and steps STEPC and STEPD for 
JOBA, (2) the JOB statement and STEPE for JOBB, and (3) the JOB statement 
and STEPJ for JOBC. The input data set contains three jobs: JOBA, which 
includes STEPA, STEPB, STEPC, and STEPD; JOB B, which includes STEPE, 
STEPF, and STEPG; and JOBC, which includes STEPH and STEPJ. 
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The example follows: 


//EDIT2 JOB O09#440,SMITH 

jf EXEC PGM=IEBEDIT 

JF SIYSPRINT DD SYSOUT=A 

TI SISIT 1 DD DISP=( OLD, KEEP ), VOLUME=SER=001234, 


// UNIT=2400-2 
//SYSUT2 DD  DSNAME=OUTSTRM, UNIT=2400-2,DISP=(NEW,KEEP ), 
// DCB=( DEN=1,RECFM=F , LRECL=80, BLKSIZE=80, 
Jd TRUCHSC ) DAREIH( 250) 
//SYSIN DD * 
EDIT  START=JOBA, TYPE=INCLUDE, STEPNAME=STEPC,STEPD 
EDIT  START=JOBB, TYPE=INCLUDE, STEPNAME=STEPE 
EDIT  START=JOBC, TYPE=INCLUDE, STEPNAME=STEPJ 
/* 


The control statements are discussed below: 


e SYSUT1 DD defines the input data set. The data set resides on a 7-track, 
standard-labeled tape volume (001234). 


e SYSUT2 DD defines the output data set. The data set is to reside as the 
second data set on a 7-track, standard-labeled tape volume (001235). 


e SYSIN DD defines the control data set, which follows in the input stream. 


e The EDIT statements copy the indicated JOB statements and job steps. 


This example copies: (1) the JOB statement and steps STEPF and STEPG for 
JOBB and (2) the JOB statement and STEPH, excluding STEPJ, for JOBC. The 
input data set contains three jobs: JOBA, which includes STEPA, STEPB, 
STEPC, and STEPD; JOBB, which includes STEPE, STEPF, and STEPG; and 
JOBC, which includes STEPH and STEPJ. 


The example follows: 


J/PDTTS JOB 09#440,SMITH 
EXEC PGM=IEBEDIT 
//SYSPRINT DD  SYSOUT=A 
//SYSUT1 DD  DSNAME=INSET,UNIT=2314,DISP=(OLD,KEEP), 
// VOLUME=SER=231400 
//SYSUT2 DD  DSNAME=OUTTAPE, UNIT=2400,LABEL( ,NL), 
// DCB=( DEN=2,RECFM=F, LRECL=80,BLKSIZE=80 ), 
jf DISP=(jREEP) 
//SYSIN DD * 
EDIT  START=JOBB, TYPE=INCLUDE, STEPNAME=STEPF-STEPG 
EDIT  START=JOBC,TYPE=EXCLUDE, STEPNAME=STEPJ 


/* 
The control statements are discussed below: 


¢ SYSUT1 DD defines the input data set. The data set resides on a 2314 
volume (231400). 


¢ SYSUT2 DD defines the output data set. The data set is to reside as the first 
or only data set on an unlabeled, 9-track (800 bits per inch) tape volume. 


e SYSIN DD defines the control data set, which follows in the input stream. 


e The EDIT statements copy selected JOB statements and job steps. 
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IEBEDIT Example 4 


IEBEDIT Example 5 
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This example copies the JOBA JOB statement, the job step STEPF, and all the 
steps that follow it. The input data set contains one job (JOBA), which includes 
STEPA, STEPB, ... STEPL. Job steps STEPA through STEPE are not included 
in the output data set. 


The example follows: 


//EDIT4 JOB O9#440,SMITH 
Jp BAEC -PGM=IF BEDIT 
7/SYSPRINT DD SYSOUT=A 
//SYSUT1 DD DSNAME=INSTREAM, UNIT=2314,DISP=(OLD,KEEP), 
// VOLUME=SER=231400 
7/ SYSUT2 DD DSNAME=OUTSTREM, UNI T=2314,DISP=( ,KEEP), 
// DCB=( RECFM=F, LRECL=80,BLKSIZE=80 ), 
// VOLUME=SER=231401,SPACE=( TRK, 2 ) 
JISYSIN DD * 
EDIT START=JOBA, TYPE=POSITION, STEPNAME=STEPF 
/* 


The control statements are discussed below: 


¢ SYSUT1 DD defines the input data set. The data set resides on a 2314 or 
2319 volume (231400). 


e SYSUT2 DD defines the output data set. The data set is to reside on a 2314 
volume (231401). Two tracks are allocated for the output data set. 


e SYSIN DD defines the control data set, which follows in the input stream. 
e EDIT copies the JOB statement and job steps STEPF through STEPL. 


This example copies the entire input (SYSUT1) data set. The record containing 
the characters “‘..*” in columns 1 through 3 is converted to a /* statement in the 
output data set. 


The example follows: 


J//EDITS JOB O0O9#440,SMITH 
J / EXEC PGM=IEBEDIT 
//SYSPRINT DD SYSOUT=A 
//SYSUT2 DD DSNAME=OUTTAPE, UNIT=2400, VOLUME=SER=001234, 
// DCB=( RECFM=F,LRECL=80,BLKSIZE=80 ), 
// DISP=(NEW,KEEP ) 
//SYSIN DD DUMMY 
//SYSUT1 DD DATA 
//BLDGDGIX JOB 
EXEC PGM=IEHPROGM 
//SYSPRINT DD SYSOUT=A 
//DD1 DD UNIT=2314,VOLUME=SER=111111,DISP=OLD 
//SYSIN DD ** 
BLDG  INDEX=A.B.C,ENTRIES=10,EMPTY 

* 
/* 
The control statements are discussed below: 


e SYSUT2 DD defines the output data set. The data set is to reside as the first 
data set on a 9-track tape volume (001234). 


e SYSIN DD defines a dummy control data set. 


e SYSUT1 DD defines the input data set, which follows in the input stream. The 
job is terminated when the termination statement (/*) is encountered. 
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IEBGENER is a data set utility used to copy a sequential data set or a 
partitioned member, or to create a partitioned data set from a sequential or 
partitioned member used as input. (See “Introduction” for general data set utility 
information.) IEBGENER can be used to expand an existing partitioned data set 
by creating partitioned members and merging them into the data set that is to be 
expanded. 


IEBGENER provides optional editing facilities and exits for user routines that 
process labels, manipulate input data, create keys, and handle permanent 
input/output errors. Refer to ‘‘“Appendix A: Exit Routine Linkage” for a 
discussion of linkage conventions that are applicable when user routines are 
provided. 


IEBGENER can be used to: 

e Create a backup copy of a sequential data set or a partitioned member. 

e Produce a partitioned data set from sequential input. 

e Expand a partitioned data set. 

e Produce an edited sequential or partitioned data set. 

e Reblock or change the logical record length of a data set. 

e Copy user labels on sequential output data sets. 

At the completion or termination of IEBGENER, the highest return code 
C encountered within the program is passed to the calling program. 


Creating a Backup Copy 


A backup copy of a sequential data set or partitioned member can be produced 
by copying the data set or member to any IBM-supported output device. For 
example, a copy can be made from tape to tape, from direct access to tape, etc. 


A data set that resides on a direct access volume can be copied to its own 
volume, provided that its data set name is changed. A partitioned data set cannot 
reside on a magnetic tape volume. 


Producing a Partitioned Data Set from Sequential Input 


IEBGENER can be used to produce a partitioned data set from sequential 
output. Through the use of utility control statements, the user can logically divide 
the sequential data set into record groups and assign member names to the 
record groups. IEBGENER places the newly created members in a partitioned 
output data set. 


Note: A partitioned data set cannot be produced if an input or output data set 
contains spanned records. 


Figure 28 shows how a partitioned data set is produced from a sequential data 
set used as input. The left-hand side of the figure shows the sequential data set. 
Utility control statements are used to divide the sequential data set into record 
groups and to provide a member name for each record group. The right-hand 
side of the figure shows the partitioned data set produced from the sequential 
input. 
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Figure 28. Creating a Partitioned Data Set from Sequential Input Using IEBGENER 


Data Set -) 


An expanded data set is a data set into which an additional member or members 
have been merged. IEBGENER creates the members from sequential input and 

places them in the data set being expanded. The merge operation—the ordering 
of the partitioned directory—is automatically performed by the program. 


Figure 29 shows how sequential input is converted into members that are merged 
into an existing partitioned data set. The left-hand side of the figure shows the 
sequential input that is to be merged with the partitioned data set shown in the 
middle of the figure. Utility control statements are used to divide the sequential 
data set into record groups and to provide a member name for each record 
group. The right-hand side of the figure shows the expanded partitioned data set. 
Note that members B, D, and E from the sequential data set were placed in 
available space and that they are sequentially ordered in the partitioned 
directory. 


Producing an Edited Data Set 
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IEBGENER can be used to produce an edited sequential or partitioned data set. 
Through the use of utility control statements, the user can specify editing 
information that applies to a record, a group of records, selected groups of 
records, or an entire data set. 


An edited data set can be produced by: 
e Rearranging or omitting defined data fields within a record. 


e Supplying literal information as replacement data. 


e Converting data from packed-decimal to unpacked-decimal mode, 
unpacked-decimal to packed-decimal mode, or H-set BCD to EBCDIC mode. 


Sequential Existing Expanded 
Input data set data set 


Utility contro 
define record 
Name membe 


Directory 
McHERG 


LASTREC 


Available space 


LASTREC 


Figure 29. Expanding a Partitioned Data Set Using IEBGENER 


Figure 30 shows part of an edited sequential data set. The left-hand side of the 
figure shows the data set before editing is performed. Utility control statements 
are used to identify the record groups to be edited and to supply editing 
information. In this figure, literal replacement information is supplied for 
information within a defined field. (Data is rearranged, omitted, or converted in 
the same manner.) The BBBB field in each record in the record group is to be 
replaced by CCCC. The right-hand side of the figure shows the data set after 
editing. 


Utility control statement 
Defines record group, contains 
literal replacement data (CCCC). 
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the group. 


Record 
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Figure 30. Editing a Sequential Data Set Using IEBGENER 
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Note: IEBGENER cannot be used to edit a data set if the input and output data 
sets consist of VS or VBS records and have equal block sizes and logical record 
lengths. In this case, any utility control statements that specify editing are 
ignored; IEBGENER performs a Straight copy; that is, for each physical record 
read from the input data set, the utility writes an unedited physical record on the 
output data set. 


Logical Record Length 


IEBGENER can be used to produce a reblocked output data set containing 
either fixed or variable records. In addition, the program can produce an output 
data set having a logical record length that differs from the input logical record 
length. 


IEBGENER uses the following input: 


e« An input data set, which contains the data that is to be copied, edited, 
converted into a partitioned data set, or converted into members to be merged 
into an existing data set. The input is either a sequential data set or a member 
of a partitioned data set. 


e A control data set, which contains utility control statements. The control data 
set is required if editing is to be performed or if the output data set is to be a 
partitioned data set. 


IEBGENER produces the following output: 


e An output data set, which can be either sequential or partitioned. The output 
data set can be either a new data set (created during the current job step) or 
an existing partitioned data set that is to be expanded. 


e A message data set, which contains informational messages (for example, the 
contents of utility control statements) and any error messages. 


IEBGENER provides a return code to indicate the results of program execution. 
The return codes and their meanings are: 


e OO, which indicates successful completion. 


e 04, which indicates probable successful completion. A warning message is 
written. 


e 08, which indicates that processing was terminated after the user requested 
processingof user header labels only. 


¢ 12, which indicates an unrecoverable error. The job step is terminated. 


e 16, which indicates that a user routine passed a return code of 16 to 
IEBGENER.The job step is terminated. 


IEBGENER is controlled by job control statements and utility control 
statements. The job control statements are required to execute or invoke 
IEBGENER and to define the data sets that are used and produced by the 
program. The utility control statements are used to control the functions of 
IEBGENER. 


Table 17 shows the job control statements necessary for using IEBGENER. 


Table 17. IEBGENER Job Control Statements 


Statement Use 
JOB Initiates the job. 
EXEC Specifies the program name (PGM=IEBGENER) or, if the job control 


Statements reside in a procedure library, the procedure name. 


SYSPRINT DD _ Defines a sequential message data set. The data set can be written to a 
system output device, a tape volume, or a direct access volume. 


SYSUTI!I DD Defines the input data set. It can define a sequential data set or a member 
of a partitioned data set. 


SYSUT2 DD Defines the output data set. It can define a sequential data set, a member of 
a partitioned data set, or a partitioned data set. 


SYSIN DD Defines the control data set, or specifies DUMMY when the output is 
sequential and no editing is specified. The control data set normally resides 
in the input stream; however, it can be defined as a member within a 
library of partitioned members. 


IEBGENER always uses two buffers, regardless of what was specified in the 
DCB. 


If both the SYSUT1 and the SYSUT2 DD statements specify standard user labels 
(SUL), IEBGENER copies user labels from SYSUT1 to SYSUT2. See 
‘‘Appendix E: Processing User Labels’ for a discussion of the available options 
for user label processing. 


Both the input data set and the output data set can contain fixed, variable, 
undefined, or variable-spanned records. These records can be reblocked by the 
specification of a new maximum block length on the SYSUT2 DD statement. 
During reblocking, if the output data set resides on a direct access volume: 


e For fixed or variable records, keys can be retained only by using the 
appropriate user exit. 


e For variable-spanned records, keys can never be retained. 
Refer to OS/VS Data Management Services Guide, GC26-3783, for 
information on estimating space allocations. 


Restrictions 
¢ The SYSPRINT DD statement is required for each use of IEBGENER. 
e The block size for the SYSPRINT data set must be a multiple of 121. The 


block size for the SYSIN data set must be a multiple of 80. Any blocking 
factor can be specified for these block sizes. 


e Space must be allocated for an output data set (SYSUT2 DD statement) that 
is to reside on a direct access device unless the data set is an expanded data 
set, in which case space must not be allocated. 


e If the output data set is on a card punch or a printer, the user must specify 
DCB information on the SYSUT2 DD statement. DCB parameters in a 
SYSUT2 DD statement defining an expanded partitioned data set must be 
compatible with the specifications made when the data set was originally 
created. 


¢ The SYSIN DD statement is required for each use of IEBGENER. 


¢ Concatenated data sets with unlike attributes are not allowed as input to 
IEBGENER. For information on concatenated data sets, see OS/VS Data 
Management Services Guide , GC26-3783. 
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IEBGENER is controlled by utility control statements. The statements and the 
order in which they must appear are: 


e GENERATE statement, which is used to indicate the number of member 
names and alias names, record identifiers, literals, and editing information 
contained in the control data set. 


¢« EXITS statement, which is used to indicate that user routines are provided. 
e LABELS statement, which is used to specify user-label processing. 


¢ MEMBER statement, which is used to specify the member name and alias of a 
member of a partitioned data set to be created. 


e RECORD statement, which is used to define a record group to be processed 
and to supply editing information. 


The control statements are included in the control data set as required. If no 
utility control statements are included in the control data set, the entire input 
data set is copied sequentially. 


When the output is to be sequential and editing is to be performed, one 
GENERATE statement and as many RECORD statements as required are used. 
If user exits are provided, an EXITS statement is used. 


When the output is to be partitioned, one GENERATE statement, one 
MEMBER statement per output member, and RECORD statements, as required, 
are used. If user exits are provided, an EXITS statement is used. 


The GENERATE statement is used when: (1) output is to be partitioned, (2) 
editing is to be performed, or (3) user routines are provided and/or label 
processing is specified. 


The GENERATE statement must appear before other statements. If it contains 
errors or is inconsistent with other statements, IEBGENER is terminated. 


The format of the GENERATE statement is: 


where: 


MAXNAME=2= n 
specifies a number that is no less than the total number of member names and 
aliases appearing in subsequent MEMBER statements. MAXNAME is required 
if there are one or more MEMBER statements. 


MAXFLDS= n 
specifies a number that is no less than the total number of FIELD parameters 
appearing in subsequent RECORD statements. MAXFLDS is required if there 
are any FIELD parameters in subsequent RECORD statements. 


MAXGPS= n 
specifies a number that is no less than the total number of IDENT parameters 
appearing in subsequent RECORD statements. MAXGPS is required if there 
are any IDENT parameters in subsequent RECORD statements. 


EXITS Statement 


MAXLITS= n 
specifies a number that is no less than the total number of characters 
contained in the FIELD literals of subsequent RECORD statements. 
MAXLITS is required if the FIELD parameters of subsequent RECORD 
Statements contain literals. MAXLITS does not pertain to literals used in 
IDENT parameters. 


The EXITS statement is used to identify exit routines supplied by the user. 
Linkages to and from exit routines are discussed in ““Appendix A: Exit Routine 
Linkage.” 


The EXITS statement is used when user routines are provided. 
The format of the EXITS statement is: 


[ label] EXITS [INHDR= routinename | 
[OUTHDR= routinename | 
[INTLR= routinename ] 
[OUTTLR= routinename | 
[KEY = routinename | 
[DATA= routinename | 
(fOERROR= routinename | 
[TOTAL=( routinename, size )] 


where: 


INHDR= routinename 
specifies the symbolic name of a routine that processes user input header 
labels. 


OUTHDR= routinename 
specifies the symbolic name of a routine that creates user output header labels. 
OUTHDR is ignored if the output data set is partitioned. 


INTLR= routinename 
specifies the symbolic name of a routine that processes user input trailer 
labels. 


OUTTLR= routinename 
specifies the symbolic name of a routine that processes user output trailer 
labels. OUTTLR is ignored if the output data set is partitioned. 


KEY= routinename 
specifies the symbolic name of a routine that creates the output record key. 
(This routine does not receive control when a data set consisting of VS or 
VBS type records is processed because no processing of keys is permitted for 
this type of data.) 


DATA= routinename 
specifies the symbolic name of a routine that modifies the physical record 
(logical record for VS or VBS type records) before it is processed by 
IEBGENER. 


IOERROR2= routinename 
specifies the symbolic name of a routine that handles permanent input/output 
error conditions. 
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TOTAL= 
specifies that exits to a user’s routine are to be provided prior to writing each 
record. The keyword OPTCD=T must be specified for the SYSUT2 DD 
statement. TOTAL is valid only when the utility is used to process sequential 
data sets. These values must be coded: 


routinename 
specifies the name of a user-supplied totaling routine. 


size 
specifies the number of bytes needed to contain totals, counters, pointers, 
etc. 


For a detailed discussion of the processing of user labels as data set descriptors, 
and for discussion of user label totaling, refer to ‘‘Appendix E: Processing User 
Labels.” 


The LABELS statement specifies whether or not user labels are to be treated as 
data by IEBGENER. For a detailed discussion of this option, refer to 
“Processing User Labels as Data,” in ‘‘Appendix E: Processing User Labels.” 


The LABELS statement is used when the user wants to specify that: (1) no user 
labels are to be copied to the output data set, (2) user labels are to be copied to 
the output data set from records in the data portion of the SYSIN data set, or 
(3) user labels are to be copied to the output data set after they are modified by 
the user’s label processing routines. If more than one valid LABELS statement is 
included, all but the last LABELS statement are ignored. 


The format of the LABELS statement is: 


where: 


DATA= 
specifies whether user labels are to be treated as data by IEBGENER. These 
values can be coded: 


YES 
specifies that any user labels that are not rejected by a user’s label 
processing routine are to be treated as data. Processing of labels as data 
ends in compliance with standard return codes. If no value is entered, YES 
is assumed. 


NO 
specifies that user labels are not to be treated as data. 


ALL 
specifies that user labels in the group currently being processed are to be 
treated as data regardless of any return code. A return code of 16 causes 
JEBGENER to complete processing the remainder of the group of user 
labels and to terminate the job step. 


ONLY 
specifies that only user header labels are to be treated as data. User header 
labels are processed as data regardless of any return code. The job 
terminates upon return from the OPEN routine. 


J 


C 


MEMBER Statement 


RECORD Statement 


INPUT 
specifies that user labels for the output data set are supplied as 80-byte 
input records in the data portion of SYSIN. The number of input records 
that should be treated as user labels must be identified by a RECORD 
statement. 


The MEMBER statement is used when the output is to be partitioned. One 
MEMBER statement must be included for each member to be created by 
IEBGENER. The MEMBER statement provides the name and aliases of a 
member that is to be created. 


All RECORD statements following a MEMBER statement pertain to the member 
named in that MEMBER statement. If no MEMBER statements are included, 
the output data set is organized sequentially. 


The format of the MEMBER statement is: 


where: 


NAME =(nzame |, alias |...) 
specifies a member name followed by a list of its aliases. If only one name 
appears in the statement, it need not be enclosed in parentheses. 


The RECORD statement is used to define a record group and to supply editing 
information. A record group consists of records that are to be processed 
identically. 


The RECORD statement is used when: (1) the output is to be partitioned, (2) 
editing is to be performed, or (3) user labels for the output data set are to be 
created from records in the data portion of the SYSIN data set. The RECORD 
statement defines a record group by identifying the last record of the group with 
a literal name. 


If no RECORD statement is used, the entire input data set or member is 
processed without editing. More than one RECORD statement may appear in the 
control statement stream for IEBGENER. 


Within a RECORD statement, one IDENT parameter can be used to define the 
record group; one or more FIELD parameters can be used to supply the editing 
information applicable to the record group; and one LABELS parameter can be 
used to indicate that this statement is followed immediately by output label 
records. 


The format of the RECORD statement is: 


IEBGENER Program 139 


where: 


IDENT= 
identifies the last record of the input group to which the FIELD parameters or 
MEMBER statement applies. If the RECORD statement is not followed by 
additional RECORD or MEMBER statements, IDENT also defines the last 
record to be processed. If IDENT is omitted, the remainder of the input data 
is considered to be in one record group; subsequent RECORD and MEMBER 
statements are ignored. These values can be coded: 


length 
specifies the length (in bytes) of the identifying name. The length cannot 
exceed eight characters. 


‘name’ 
specifies the exact literal that identifies the last input record of a record 
group. If no match for name is found, the remainder of the input data is 
considered to be in one record group; subsequent RECORD and MEMBER 
statements are ignored. 


input-location 
specifies the starting location of the field that contains the identifying name 
in the input records. 


FIELD= 
specifies field-processing and editing information. Only the contents of 
specified fields in the input record is copied to the output record. The values 
that can be coded are: 


length 
specifies the length (in bytes) of the input field or literal to be processed. If 
length is not specified, a length of 80 bytes is assumed. If a literal is to be 
processed, a length of 40 bytes or less must be specified. 


input-location 
specifies the starting byte of the field to be processed. If input-location is 
not specified, byte 1 is assumed. 


‘literal’ 
specifies a literal (maximum length of 40 bytes) to be placed in the 
specified output location. If a literal contains apostrophes, each apostrophe 
must be written as two consecutive apostrophes. 


conversion 
specifies a two-byte code that indicates the type of conversion to be 
performed on this field. If no conversion is specified, the field is moved to 
the output area without change. The values that can be coded are: 


PZ 
specifies that data (packed decimal) is to be converted to unpacked 
decimal data. 


ZP 
specifies that data (unpacked decimal) is to be converted to packed 
decimal data. 


HE 
specifies that data (H-set BCD) is to be converted to EBCDIC. 


output-location 
specifies the starting location of this field in the output records. If 
output-location is not specified, byte 1 is assumed. 
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LABELS= n 
is an optional parameter that indicates the number of records in the SYSIN 
data set to be treated as user labels. The number n, which is a number from 
1 to 8, must specify the exact number of label records that follow the 
RECORD statement. If this parameter is included, DATA=INPUT must be 
coded on a LABELS statement before it in the input stream. 


I 


=r 


conversion is specified in FIELD, the following restrictions apply: 


e PZ-type (packed-to-unpacked) conversion is impossible for packed-decimal 
records longer than 16K bytes. 


e For ZP-type (unpacked-to-packed) conversion, the normal 32K-byte maximum 
applies. 


e When the ZP parameter is specified, the conversion is performed in place. The 
original unpacked field is replaced by the new packed field. Therefore, the ZP 
parameter must be omitted from subsequent references to that field. If the 
field is needed in its original unpacked form, it must be referenced prior to the 
use of the ZP parameter. 


If conversion is specified in the FIELD parameter, the length of the output 
record can be calculated for each conversion specification. When L is equal to 
the length of the input record, the calculation is made, as follows: 


e For a PZ (packed-to-unpacked) specification, 2L - 1. 


¢ For a ZP (upacked-to-packed) specification, (L/2) + C. If L is an odd 
number, C is 1/2; if L is an even number, C is 1. 


¢ For an HE (H-set BCD to EBCDIC) specification, L. 


If both output header labels and output trailer labels are to be contained in the 
SYSIN data set, the user must include one RECORD statement (including the 
LABELS parameter), indicating the number of input records to be treated as user 
labels, for header labels and one for trailer labels. The first such RECORD 
statement indicates the number of user header labels; the second indicates the 
number of user trailer labels. If only output trailer labels are included in the 
SYSIN data set, a RECORD statement must be included to indicate that there 
are no output header labels in the SYSIN data set (LABELS=0). This statement 
must precede the RECORD LABELS=n statement which signals the start of 
trailer label input records. 


For a detailed discussion of the LABELS option, refer to ‘“‘Processing User 
Labels As Data,” in ““Appendix E: Processing User Labels.” 


Note: IDENT and FIELD parameters are ignored in straight copy processing of 
data sets that contain VS or VBS records. 


IEBGENER Examples 


The examples that follow illustrate some of the uses of IEBGENER. Table 18 
can be used as a quick reference guide to IEBGENER examples. The numbers in 
the ‘“Example’’ column point to the examples that follow. 
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Table 18. IEBGENER Example Directory 


Operation 
COPY 


COPY -with 
editing 
COPY-with 
editing 
COPY-—with 
editing 
PRINT 


CONVERT 


COPY-with 
editing 
COPY-with 
editing 


COPY-with 
editing 


COPY-—with 
editing 


Data Set 


Organization Devices 


Sequential 
Sequential 
Sequential 
Sequential 
Sequential 


Sequential 
input, 
Partitioned 
output 


Sequential 


Sequential 


Sequential 


Sequential 


Card Reader, 


Tape 


Card Reader, 


Tape 


Card Reader, 


Tape 


Card Reader, 


2314 Disk 


Card Reader, 


Printer 


Tape, 
2314 Disk 


3330 Drum 


Tape 


2314 Disk 


Tape 


Comments 


Blocked output. 
Blocked output. 


Blocked output. Input includes 
// cards. 


Blocked output. Input includes 
// cards. 


Input includes // cards. System 
output device is a printer. 


Blocked output. Three members 
are to be created. 


Blocked output. Two members are 


to be merged into existing data set. 


Blocked output. Data set edited as 
one record group. 


Blocked output. New record length 
specified for output data set. Two 
record groups specified. 


Blocked output. Data set edited as 
One record group. 


Example 


In this example, a card-input, sequential data set is to be copied to a 9-track tape 


volume. 


The example follows: 


i 7 COTOTAPE «JOB 


O9#6600,SMITH 


as EXEC PGM=IEBGENER 
//SYSPRINT DD  SYSOUT=A 
//SYSIN DD DUMMY 
//SYSUT2 


fforsur | 


DD DSNAME=OUTSET, UNIT=2400, LABEL=(,SL), 
// DISP=( ,KEEP ), VOLUME=SER=001234, 
// DCB=( RECFM=FB, LRECL=80, BLKSIZE=2000 ) 


DD * 


(input card data set) 


/* 


The control statements are discussed below: 


e SYSIN DD defines a dummy data set. No editing is to be performed; 
therefore, no utility control statements are needed. 


e SYSUT2 DD defines the output data set. The data set is written to a 9-track 
tape volume at a density of 800 bits per inch. The data set is to reside as the 
first (or only) data set on the volume. 


e SYSUT1 DD defines the card-input data set. The data set can contain no // 


cards. 


In this example, a card-input, sequential data set is to be copied to a 7-track tape 
volume. The control data set is a member of a partitioned data set. 


C 
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The example follows: 


//CDTOTAPE JOB 09#660,SMITH 


eA EXEC PGM=IEBGENER 
//SYSPRINT DD SYSOUT=A 
ff SLSIN DD DSNAME=CNTRLIBY(STMNTS ), UNIT=2314, 


// DISP=(OLD,KEEP ), VOLUME=SER=111112, 

// DCB=( RECFM=F, LRECL=80, BLKSIZE=80 ) 

//SYSUT2. DD  DSNAME=OUTSET, UNIT=2400-2,LABEL=(,SL), 
// DCB=( DEN=1,RECFM=FB, LRECL=80, BLKSIZE=2000, 

// TRICH=C ),DISP=( ,KEEP ), VOLUME=SER=001234 

//SYSUT1 DD * 


(input card data set) 
{* 
The control statements are discussed below: 


e SYSIN DD defines the control data set, which contains the utility control 
Statements. The control statements reside as a member, STMNTS, in a 
partitioned data set. 


e SYSUT2 DD defines the output data set. The data set is written as the first or 
only data set on the volume. It is written at a density of 556 bits per inch on 
a 7-track tape volume. 


« SYSUT1 DD defines the card-input data set. The data set can contain no // 
cards. 


In this example, a card-input, sequential data set is to be copied to a 9-track tape 
volume. The input contains cards that have slashes (//) in columns 1 and 2. The 
control data set is a member of a partitioned data set. 


The example follows: 


//CDTOTAPE JOB 09#660,SMITH 


i. EXEC PGM=IEBGENER 
//SYSPRINT DD SYSOUT=A 
{/SXYSIN DD DSNAME=CNTRLIBY( STMNTS ), UNIT=2314, 


// DISP=(OLD,KEEP ), VOLUME=SER=111112, 

// DCB=(RECFM=F , LRECL=80, BLKSIZE=80 ) 

//SYSUT2. DD  DSNAME=OUTSET,UNIT=2400,LABEL=(2,SL), 
// VOLUME=SER=001234,DCB=( RECFM=FB, 

// LRECL=80, BLKSIZE=2000 ),DISP=( , KEEP ) 

//SYSUT1 DD DATA 


(input card data set, including // cards) 
j* 
The control statements are discussed below: 


¢ SYSIN DD defines the data set containing the utility control statements. The 
statements reside as a member, STMNTS, in a partitioned data set. 


e SYSUT2 DD defines the copied sequential data set (output). The data set is 
written as the second data set on the specified tape volume. 


¢ SYSUT1 DD defines the card-input data set. The data set is to be edited as 
specified in the utility control statements (not shown). The input data set 
contains // cards. 


In this example, a card-input, sequential data set is to be copied to a 2314 
volume. The input data set contains // cards. 
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The example follows: 


J//COTODISK. JOB 09#660,SMITH 
EXEC PGM=IEBGENER 
//SYSPRINT DD SYSOUT=A 
TI SYSIN DD DSNAME=CNTRLIBY(STMNTS ), UNIT=2314, 
// DISP=(OLD,KEEP ), VOLUME=SER=111112, 
// DCB=( RECFM=F, LRECL=80, BLKSIZE=80 ) 
J FOYSUT2Z DD DSNAME=OUTSET, UNIT=2314,VOLUME=SER=111113, 
// DISP=(.,;KEEP ),SPACH=(TRK,(.10,10)), 
// DCB=( RECFM=FB, LRECL=80,BLKSIZE=2000 ) 
JfSLSUT 1 DD DATA 


(input card data set, including // cards) 

/* 

The control statements are discussed below: 

« SYSIN DD defines the control data set, which contains the utility control 


statements. The control statements reside as a member, STMNTS, in a 
partitioned data set. 


e SYSUT2 DD defines the output data set. Ten tracks of primary storage space 
and ten tracks of secondary space are allocated for the data set on a 2314 
volume. 


e SYSUT1 DD defines the card-input data set. The data set is to be edited as 
specified in the utility control statements (not shown). The input data set 
contains // cards. 


In this example, the content of a card data set is to be printed. The printed 
output is to be left-aligned, with one 80-byte record appearing on each line of 
printed output. 


The example follows: 


//CDTOPTR JOB 09#660,SMITH 


Pie EXEC PGM=IEBGENER 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD DUMMY 


JS SLSUT2 DD SYSOUT=A , DCB=( RECFM=F, LRECL=80, BLKSIZE=80 ) 
//S (SUT DD DATA 


(input card data set, including // cards) 
/* 
The control statements are discussed below: 


e SYSIN DD defines a dummy data set. No editing is to be performed; 
therefore, no utility control statements are required. 


e SYSUT2 DD indicates that the output is to be written on the system output 
device (printer). Carriage control can be specified by changing the 
RECFM=F subparameter to RECFM=FA. 


¢ SYSUT1 DD defines the input card data set. The input data set contains // 
cards. 


In this example, a partitioned data set (consisting of three members) is to be 
created from sequential input. 


IEBGENER Example 7 


The example follows: 


//TAPEDISK JOB 09#660,SMITH 
as EXEC PGM=TEBGENER 
J/7SYSPRINT DD SYSOUT=A 
G7 SV SU DD DSNAME=INSET,UNIT=2400, LABEL=(,SL), 
// DISP=(OLD,KEEP ), VOLUME=SER=001234, 
// DCB=(RECFM=F,LRECL=80, BLKSIZE=80 ) 
fF SSUT2Z DD DSNAME=NEWSET, UNIT=2314,DISP=(,KEEP), 
7/ VOLUME=SER=111112,SPACE=( TREK, ( 10,5,5:)); 
// DCB=( RECFM=FB, LRECL=80, BLKSIZE=2000 ) 
IGS TSN DD * 
GENERATE MAXNAME=3 , MAXGPS=2 

MEMBER NAME=MEMBER|] 
GROUP1 RECORD IDENT=( 85.” FIRSTMEM* 5-1) °) 

MEMBER NAME=MEMBER2 
GROUP2 RECORD IDENT=( 8, 'SECNDMEM' , 1 ) 

MEMBER NAME=MEMBER3 
/* 


The control statements are discussed below: 


e SYSUT1 DD defines the input data set (INSET). The data set was originally 
written on a 9-track tape volume at a density of 800 bits per inch. 


e SYSUT2 DD defines the output partitioned data set (NEWSET). The data set 
is to be placed on a 2314 volume. Ten tracks of primary space, five tracks of 
secondary space, and five blocks (256 bytes each) of directory space are 
allocated to allow for future expansion of the data set. The output records are 
blocked to reduce the space required by the data set. 


e SYSIN DD defines the control data set, which follows in the input stream. The 
utility control statements are used to create members from sequential input 
data; the statements do not specify any editing. 


e GENERATE indicates that: (1) three member names are included in 
subsequent MEMBER statements and (2) the IDENT parameter appears twice 
in subsequent RECORD statements. 


e The first MEMBER statement assigns a member name (MEMBER|1) to the 
first member. 


e The first RECORD statement (GROUP1) identifies the last record to be 
placed in the first member. The name of this record (FIRSTMEM) appears in 
bytes 1 through 8 of the input record. 


¢ The remaining MEMBER and RECORD statements define the second and 
third members. 


In this example, sequential input is to be converted into two partitioned 
members. The newly created members are to be merged into an existing 
partitioned data set. User labels on the input data set are to be passed to the 
user exit routines. 
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The example follows: 


//DISKTODK JOB 09#660,SMITH 


// 


EXEC PGM=IEBGENER 


//SYSPRINT DD SYSOUT=A ’ 

LISLSUL |) DD DSNAME=INSET, UNIT=3330,DISP=(OLD,KEEP ), ; 

// VOLUME=SER=111112,DCB=( RECFM=FB, LRECL=80, wo 
// BLKSIZE=20000 ), LABEL=( ,SUL) 

77S tSUTZ DD DSNAME=EXISTSET, UNIT=3330,DISP=(MOD,KEEP), 

// NJOLUME=SER=111113,DCB=( RECFM=FB, LRECL=80, 

// BLKSIZE=2000 ) 

JJ oO EN DD - 


GENERATE MAXNAME=3 , MAXGPS=1 
BALTS INHDR=ROUT 1, INTLR=ROUT2 
MEMBER NAME=( MEMX, ALIASX ) 


GROUP1 RECORD IDENT=(8,'FIRSTMEM', 1 ) 


/* 


MEMBER NAME=MEMY 


The control statements are discussed below: 


SYSUT1 DD defines the input data set (INSET). The input data set, which 
resides on a 3330 volume, has standard and user labels. 


SYSUT2 DD defines the output partitioned data set (EXISTSET). The 
members created during this job step are merged into the partitioned data set. 
The output records are blocked to reduce the space required by the new 
members. 


SYSIN DD defines the control data set, which follows in the input stream. The 
utility control statements are used to create members from sequential input 
data; the statements do not specify any editing. 


GENERATE indicates that: (1) two member names and one alias are included 
in subsequent MEMBER statements and (2) an IDENT parameter appears in 
a subsequent RECORD statement. 5 


EXITS defines the user routines that are to process user labels. 


The first MEMBER statement assigns a member name (MEMX) and an alias 
(ALIASX) to the first member. 


The first RECORD statement identifies the last record to be placed in the first 
member. The name of this record (FIRSTMEM) appears in bytes 1 through 8 
of the input record. 


The second MEMBER statement assigns a member name (MEMY) to the 
second member. The remainder of the input data set is included in this 
member. 


In this example, a sequential input data set is to be edited and copied. 


The example follows: 


a) 
//TAPETAPE JOB 09#660,SMITH 
Lf EXEC PGM=IEBGENER 
//SYSPRINT DD  SYSOUT=A 
//SYSUT1 DD  DSNAME=OLDSET,UNIT=2400-2,DISP=(OLD,KEEP), 
// VOLUME=SER=001234,LABEL=(3,SL), 
// DCB=( RECFM=F, LRECL=80,BLKSIZE=80, TRTCH=C ) 
//SYSUT2 DD  DSNAME=NEWSET,UNIT=2400-2,DISP=(NEW,PASS), 
// DCB=( RECFM=FB, LRECL=80, BLKSIZE=2000, TRTCH=C), 
// VOLUME=SER=001235,LABEL=( ,SL) 
//SYSIN DD * 
GENERATE MAXFLDS=3,MAXLITS=11 
RECORD FIELD=(10,'****## RH! 7) 
FIELD=(5,1,HE,11),FIELD=(1,'=',,16) 
EXITS INHDR=ROUT1,OUTTLR=ROUT2 
LABELS  DATA=INPUT 
RECORD  LABELS=2 


yc 


(first header label record) 
(second header label record) 


RECORD LABELS=2 
(first trailer label record) 
(second trailer label record) 
/* 
The control statements are discussed below: 


e SYSUT1 DD defines the sequential input data set (OLDSET). The data set 
was originally written as the third data set (800 bits per inch) on a 7-track 
tape volume. 


e SYSUT2 DD defines the sequential output data set (NEWSET). The data set 
is written as the first or only data set on a 7-track tape volume. A density of 
800 bits per inch and data conversion are specified for the write operation. 
The output records are blocked to reduce the space required by the data set 
and to reduce the access time required when the data set is subsequently 
referred to. The data set is passed to a subsequent job step. 


e SYSIN DD defines the control data set, which follows in the input stream. 


e GENERATE indicates that: (1) a maximum of three FIELD parameters is 
included in subsequent RECORD statements and (2) a maximum of 11 literal 
characters are included in subsequent FIELD parameters. 


e EXITS indicates that the specified user routines require control when SYSUT1 ia 
is opened and when SYSUTZ2 is closed. 


¢ LABELS indicates that labels are included in the input stream. 


¢ The first RECORD statement controls the editing, as follows: (1) asterisks are 
placed in positions 1 through 10, (2) bytes 1 through 5 of the input record are 
converted from H-set BCD to EBCDIC mode and moved to positions 11 
through 15, and (3) an equal sign is placed in byte 16. 


« The second RECORD statement indicates that the next two records from 
SYSIN should be written out as user header labels on SYSUT2. 


e The third RECORD statement indicates that the next two records from SYSIN 
should be written as user trailer labels on SYSUT2. 
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Note: This example shows the relationship between the RECORD LABELS 
Statement and the EXITS statement. IERBGENER attempts to write a first and 
second label trailer as user labels at close time of SYSUT2 before returning 
control to the system; the user routine, ROUT2, can review these records and 
change them, if necessary. 


In this example, a sequential input data set is to be edited and copied. 
The example follows: 


7 
//DISKDISK JOB 09#660,SMITH 
If EXEC PGM=IEBGENER 
//SYSPRINT DD  SYSOUT=A 
//SYSUT1. DD  DSNAMF=OLDSET,UNIT=2314,DISP=(OLD,KEEP), 
// VOLUME=SER=111112,DCB=( RECFM=F, LRECL=100, 
ff BURST ZE=100) 
//SYSUT2 DD DSNAMF=NEWSET,UNIT=2314,DISP=(NEW,KEEP ), 
// VOLUME=SER=111113,DCB=( RECFM=FB, LRECL=80, 
// BLKSIZE=640 ), SPACF=(TRK,(20,10)) 
//SYSIN DD * 
GENERATE  MAXFLDS=4,MAXGPS=1 
EXITS | IOERROR=ERRORRT 
GROUP1 RECORD  IDENT=(8,'FIRSTGRP',1), aie 
FIELD=(21,80,,60),FIELD=(59,1,,1) 
GROUP2 RECORD FIELD=(11,90,,70),FIELD=(69,1,,1) 
/* 


The control statements are discussed below: 


e SYSUT1 DD defines the input data set (OLDSET). The logical record length 
of the input records is 100 bytes. 


¢ SYSUT2 DD defines the output data set (OUTSET). Twenty tracks of 
primary storage space and ten tracks of secondary storage space are allocated 
for the data set on a 2314 volume. The logical record length of the output 
records is 80 bytes, and the output is blocked. 


e SYSIN DD defines the control data set, which follows in the input stream. 


e GENERATE indicates that: (1) a maximum of four FIELD parameters is 
included in subsequent RECORD statements and (2) a maximum of one 
IDENT parameter appears in a subsequent RECORD statement. 


¢« EXITS identifies the user routine that handles input/output errors. 


e The first RECORD statement controls the editing of the first record group, as 
follows: (1) FIRSTGRP, which appears in bytes 1 through 8 of the input 
record, is defined as being the last record in the first group of records and (2) 
bytes 80 through 100 of each input record are moved into positions 60 
through 80 of each corresponding output record. (This example implies that 
bytes 60 through 79 of the input records in the first record group are no 
longer required; thus, the logical record length is shortened by 20 bytes.) The 
remaining bytes within each input record are transferred directly to the output 
records, specified in the second FIELD parameter. 
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e The second RECORD statement indicates that the remainder of the input 
records are to be processed as the second record group. Bytes 90 through 100 
of each input record are moved into positions 70 through 80 of the output 
records. (This example implies that bytes 70 through 89 of the input records 
from group 2 are no longer required; thus, the logical record length is 
shortened by 20 bytes.) The remaining bytes within each input record are 
transferred directly to the output records, specified in the second FIELD 
parameter. 


If the logical record length of the output data set differs from that of the input 
data set, as in this example, all positions in the output records must undergo 
editing to justify the new logical record length. 


In the example, a sequential input data set is to be edited and copied. 
The example follows: 


d2 
//TAPETAPE JOB 09#660,SMITH 
EXEC PGM=IEBGENER 
//SYSPRINT DD SYSOUT=A 
JF SLSUE) DD DSNAME=OLDSET, UNIT=2400, DISP=(OLD,KEEP), 
// VOLUME=SER=001234,LABEL=(3,SUL), 
// DCB=( RECFM=F,LRECL=80, BLKSIZE=80 ) 
FiSTSUT2 DD DSNAME=NEWSET, UNIT=2400, DISP=( NEW, PASS ), 
// VOLUME=SER=001235,LABEL=( ,SUL), 
// DCB=( RECFM=FB,LRECL=80 , BLKSIZE=2000 ) 
{/SYSIN DD * 
GENERATE MAXFLDS=3 ,MAXLITS=11 
RECORD PIELDH=(10; tee ePete 
ELE SDH (5 ghey lit ar LPL 
LABELS DATA=INPUT 
RECORD LABELS=3 


wie 
es 


(first header label record) 
(second header label record) 
(third header label record) 


RECORD LABELS=2 


(first trailer label record) 
(second trailer label record) 


/* 
The control statements are discussed below: 


¢« SYSUT1 DD defines the input data set (OLDSET). The data set was 
originally written as the third data set (800 bits per inch) on a 9-track tape 
volume. 


e SYSUT2 DD defines the output data set (NEWSET). The data set is written 
as the first or only data set on a 9-track tape volume. A density of 800 bits 
per inch is specified for the write operation. The output records are blocked to 
reduce the space required by the data set and to reduce the access time 
required when the data set is subsequently referred to. The data set is passed 
to a subsequent job step. 


e SYSIN DD defines the control data set, which follows in the input stream. 


¢ GENERATE indicates that: (1) a maximum of three FIELD parameters is 
included in subsequent RECORD statements and (2) a maximum of 11 literal 
characters are included in subsequent FIELD parameters. 


e LABELS indicates that label records are included in the input stream. 
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e The first RECORD statement controls the editing, as follows: (1) asterisks are 
placed in positions 1 through 10, (2) bytes 1 through 5 of the input record are 
converted from H-set BCD to EBCDIC mode and moved to positions 11 
through 15, and (3) an equal sign is placed in byte 16. 


e The second and third RECORD statements indicate that three 80-byte records 
(cards), to be written as user labels on the output data set, immediately 
follow. The first RECORD statement indicates that the following cards are to 
be treated as header labels. The second RECORD statement indicates that the 
following cards are to be treated as trailer labels. 
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IEBISAM Program 


IEBISAM is a data set utility used to copy an indexed-sequential data set directly 
from one direct access volume to another. (See “Introduction” for general data 
set utility information. ) 


Alternatively, IEBISAM can be used to reorganize an indexed-sequential data set 
into a sequential ( unloaded) data set and place that data set on a direct access 
Or magnetic tape volume. The unloaded data set is in a form that can be 
subsequently loaded, that is, it can be converted back into an indexed-sequential 
data set. 


Optionally, IEBISAM can be used to print the records of an indexed-sequential 
data set. 


IEBISAM can be used to: 
¢« Copy an indexed-sequential data set. 


e Create a sequential backup (transportable) copy of source data from an 
indexed-sequential data set. 


e Create an indexed-sequential data set from an unloaded data set. 
e Print an indexed-sequential data set. 


At the completion or termination of IEBISAM, the highest return code 
encountered within the program is passed to the calling program. 


Copying an Indexed-Sequential Data Set 


‘= IEBISAM can be used to copy an indexed-sequential data set directly from one 
direct access volume to another. When the data set is copied, the records marked 
for deletion are only deleted if the DELETE parameter was specified in the 
OPTCD (optional control program service) field. Those records that are 
contained in the overflow area of the original data set are moved into the 
primary area of the copied data set. The control information characteristics such 
as BLKSIZE and OPTCD can be overridden by new specifications. Caution 
should be used, however, when overriding these characteristics (see ‘““Unloaded 
Data Sets’’ in this chapter). 


Creating a Sequential Backup Copy 


An unloaded sequential data set can be created to serve as a backup or 
transportable copy of source data from an indexed-sequential data set. Records 
marked for deletion within the indexed-sequential data set are automatically 
deleted when the unloaded data set is created. When the data set is subsequently 
loaded —reconstructed into an indexed-sequential data set—records that were 
contained in the overflow area assigned to the original data set are moved 
sequentially into the primary area. 


An unloaded data set consists of 80-byte logical records. The data set contains: 
¢ Fixed records from an indexed-sequential data set. 
¢« Control information used in the subsequent loading of the data set. 


Control information consists of characteristics that were assigned to the 
indexed-sequential data set. These characteristics are: 


( ¢ Optional control program service (OPTCD) 
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e Record format (RECFM) 

e Logical record length (LRECL) 
e Block size (BLKSIZE) 

¢ Relative key position (RKP) 


¢ Number of tracks in cylinder index (NTM) 
¢« Key length (KEYLEN) 
¢ Number of overflow tracks on each cylinder (CYLOFL) 


When a load operation is specified, these characteristics can be overridden by 
new specifications in the DCB parameter of the SYSUT2 DD statement (refer to 
‘Job Control Statements” for a discussion of the SYSUT2 DD statement). 
Caution should be used, however, because checks are made to ensure that: 


1. Record format is the same as that of the original indexed-sequential data set 
(either fixed or variable length). 


2. Logical record length is less than or equal to that of the original 
indexed-sequential data set. 


3. For fixed records, the block size is equal to or a multiple of the logical record 
length of the records in the original indexed-sequential data set. For variable 
records, the block size is equal to or greater than the logical record length plus 
four. 


4. Relative key position is equal to or less than the logical record length minus 
the key length. Following are relative key position considerations: 


e If the RECFM is variable or variable blocked, the relative key position 
should be at least 4. 


e If the DELETE parameter was specified in the OPTCD field and the } 
RECFM is fixed or fixed blocked, the relative key position should be at 
least 1. 


e If the DELETE parameter was specified in the OPTCD field and the 
RECFM is variable or variable blocked, the relative key position would be 
at least 5. 


5. The key length is less than or equal to 255 bytes. 


If either RKP or KEYLEN is overridden, it might not be possible to reconstruct 
the data set. 


The number of 80-byte logical records in an unloaded data set can be determined 
by the formula: 


X = n(y+2) + 158 
78 


where x is the number of 80-byte logical records created, n is the number of 
records in the indexed-sequential data set, and y is the length of a fixed record 
or the average length of variable records. 
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Figure 31 shows the format of an unloaded data set for the first three 100-byte 
records of an indexed-sequential data set. Each is preceded by two bytes (bb) 
that indicate the number of bytes in that record. (The last record is followed by 
two bytes containing binary zeros to identify the last logical record in the 

Cc unloaded data set.) The characteristics of the indexed-sequential data set are 
contained in the first two logical records of the unloaded data set. Data from the 
indexed-sequential data set begins in the third logical record. Each logical record 
in the unloaded data set contains a binary sequence number (aa) in the first two 
bytes of the record. 


rT t™~—O 80 bytes 8 


afafbfo] Characteristics 
ap Characteristics 
fatboy bytesof data 
fafa] 24 bytes of dara bb] SA bytes of data 
aja} AB bytes of data] Bytes of data 
afep bytes oda HY 


Figure 31. An Unloaded Data Set Created Using IEBISAM 


Creating an Indexed-Sequential Data Set from an Unloaded Data Set 


An indexed-sequential data set can be created from an unloaded version of an 
indexed-sequential data set. When the unloaded data set is loaded, those records 
that were contained in the overflow area assigned to the original 
indexed-sequential data set are moved sequentially into the primary area of the 
loaded indexed-sequential data set. 


Printing the Logical Records of an Indexed-Sequential Data Set 


The records of an indexed-sequential data set can be printed or stored as a 

CC sequential data set for subsequent printing. Each input record is placed in a 
buffer from which it is printed or placed in a sequential data set. When the 
DELETE parameter is specified in the OPTCD field, each input record not 
marked for deletion is also placed in a buffer from which it is printed or placed 
in a sequential data set. Each printed record is converted to hexadecimal unless 
specified otherwise by the user. 


IEBISAM provides user exits so that the user can include his own routines to: 
e Modify records before printing. 


¢ Select records for printing or terminate the printing operation after a certain 
number of records have been printed. 


e Convert the format of a record to be printed. 


¢« Provide a record heading for each record if the record length is at least 18 
bytes. If no user routines are provided, each record is identified in sequeatial 
order on the printout. 


When a user routine is supplied for a print operation, IEBISAM issues a LOAD 
macro instruction. A BALR 14,15 instruction is used to give control to the user’s 
routine. When the user’s routine receives control, register 0 contains a pointer to 
a record heading buffer; register 1 contains a pointer to an input record buffer. 


The input record buffer has a length equal to the length of the input logical 
record. 


Figure 32 shows the record heading buffer. 
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Register 0 Accord 


number 
(decimal) 


Available to the user cece 
ae length = line length of applicable printer ———————-———_e> 


Register 1 


Input record 


ls eae length = input logical record length (LRECL) 


Figure 32. Record Heading Buffer Used by IEBISAM 


The user returns control to IEBISAM by issuing a RETURN macro instruction 
(via register 14) or by using a BR 14 instruction after restoring registers 2 
through 14. (Note that the user must save registers 2 through 14 when control is 
given to the user routine. ) 


A user routine must place a return code in register 15 before returning control to 
IEBISAM. The possible return codes and their meanings are: 


e OO, which indicates that buffers are to be printed. 


e 04, which indicates that the buffers are to be printed and the operation is to 
be terminated. 


e 08, which indicates that this input record is not to be printed; processing 
continues. 


e 12, which indicates that this input record is not to be printed; terminate the 
operation. 


IEBISAM uses an input data set; the organization of the input data set depends 
on the operation to be performed, as follows: 


e If a data set is to be copied, unloaded, or printed in logical sequence, the input 
is an indexed-sequential data set. 


e If a data set is to be loaded, the input is an unloaded sequential version of an 
indexed-sequential data set. 


IEBISAM produces as output an output data set, which is the result of the 
IEBISAM operation, and a message data set, which contains informational 
messages and any error messages. 


IEBISAM provides a return code to indicate the results of program execution. 
The return codes and their meanings are: 


e OO, which indicates successful completion. 


e (4, which indicates that a return code of 04 or 12 was passed to IEBISAM by 
the user routine. 


e 08, which indicates that an error condition occurred that caused termination of 
the operation. 


e 12, which indicates that a return code other than 00, 04, 08, or 12 was passed 
to IEBISAM from a user routine. The job step is terminated. 


¢« 16, which indicates that an error condition caused termination of the 
operation. 


Control 
© IEBISAM is controlled by job control statements. No utility control statements 
are required. 


Job Control Statements 
Table 19 shows the job control statements necessary for using IEBISAM. 


Table 19. IEBISAM Job Control Statements 


Statement Use 
JOB Initiates the job. 


EXEC Specifies the program name (PGM=IEBISAM). Additional information is 
required on the EXEC statement to control the execution of IEBISAM; see 
‘‘PARM Information on the EXEC Statement” below. 


SYSUTI DD _ Defines the input data set. 
SYSUT2 DD _ Defines the output data set. 


SYSPRINT DD Defines a sequential message data set, which can be written to a system output 
device, a tape volume, or a direct access device. 


If the block size of the SYSPRINT data set is not a multiple of 121, a default 
value of 121 is taken (no error message is issued, and no condition code is set). 
PARM Information on the EXEC Statement 


The PARM parameter on the EXEC statement is used to control the execution 
of IEBISAM. The PARM parameter is entered: 


PARM= {COPY } 

L_ {UNLOAD } 
{LOAD } 

{PRINTL } 


{*PRINTL[,N][,EXIT=routinename]’} 
The PARM values have the following meaning: 
« COPY specifies a copy operation. 
e UNLOAD specifies an unload operation. 
e LOAD specifies a load operation. 


e PRINTL specifies a print operation in which each record is converted to 
hexadecimal before printing. The N is an optional value that specifies that 
records are not to be converted to hexadecimal before printing. a 


¢« EXIT is an optional value that specifies the name of an exit routine that is to 
receive control before each record is printed. 


Note: Exit routines must be included in either the job library or the link library. 


For a COPY operation, the SYSUT2 DD statement must include a primary space 
allocation that is sufficient to accommodate records that were contained in 
overflow areas in the original indexed-sequential data set. New overflow areas 
can be specified when the data set is copied. 
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For an UNLOAD operation, specifications that are implied by default or 

included in the DCB parameter of the SYSUT2 DD statement (for example, tape 
density) must be considered when the data set is subsequently loaded. If a block 
size is specified in the DCB parameter of the SYSUT2 DD statement, it must be 


a multiple of 80 bytes. ) 


For a LOAD operation, if the input data set resides on an unlabeled tape, the 
SYSUT1 DD statement must specify a BLKSIZE that is a multiple of 80 bytes. 
Specifications that are implied by default or included in the DCB parameter of 
the SYSUT1 DD statement must be consistent with specifications that were 
implied or included in the DCB parameter of the SYSUT2 DD statement used 
for the UNLOAD operation. The SYSUT2 DD statement must include a primary 
space allocation that is sufficient to accommodate records that were contained in 
overflow areas in the original indexed-sequential data set. If new overflow areas 
are desired, they must be specified when the data set is loaded. 


For a PRINTL operation, if the device defined by the SYSUT2 DD statement is 
a printer, the specified BLKSIZE must be equal to or less than the physical 
printer size; that is 121, 133, or 145 bytes. If BLKSIZE is not specified, 121 
bytes is assumed. LRECL (or BLKSIZE when no LRECL was specified) must 
be between 55 and 255 bytes. 


If a user routine is supplied for a PRINTL operation, IEBISAM issues a LOAD 
macro instruction to make the user routine available. A BALR 14,15 instruction 
is subsequently used to give control to the routine. When the user routine 
receives control, register 0 contains a pointer to a record heading buffer; 
register 1 contains a pointer to an input record buffer. 


The following examples illustrate some of the uses of IEBISAM. Table 20 can be 
used as a quick reference guide to IEBISAM examples. The numbers in the 
‘““Example”’ column point to the examples that follow. 


J 


Table 20. IEBISAM Example Directory 


Data Set 
Operation Organization Devices Comments Example 
COPY Indexed- 2314 Disks Unblocked input; blocked output 

sequential Prime area and index separation. I 
UNLOAD Indexed- 2314 Disk, Blocked output. 

sequential, 9-track 

Sequential tape 2 
UNLOAD Indexed- 2314 Disk, Blocked output. Data set written 

sequential, 7-track as second data set on input 

Sequential tape volume. 3 
LOAD Sequential, 9-track Input data set is second data set 

Indexed- tape, on tape volume. 

sequential 2314 Disk 4 
PRINTL Indexed- 2314 Disk, Blocked input. Output not 

sequential, System converted. 

Sequential Printer 5 


In this example, an indexed-sequential data set is to be copied from two 2314 


volumes. The output data is blocked. 
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The example follows: 


//CPY JOB 09#770,SMITH 

Ty EXEC PGM=IEBISAM, PARM=COPY 

//SYSPRINT DD SYSOUT=A 

Jf SY SUT 1 DD DSNAME=ISAMO 1, VOLUME=SER=( 222222, 333333), 
/7/ DISP=(OLD, DELETE ),UNIT=(2314;2), 

// DCB=( DSORG=IS, LRECL=500, BLKSIZE=500 ) 

~7S LSI? DD DSNAME=ISAMO2( INDEX ), UNIT=2314, 

// DISP=(NEW, KEEP ), VOLUME=SER=444444, 


// DCB=( DSORG=IS, BLKSIZE=1000 ),SPACE=(CYL,(2) ) 
77D) DD DSNAME=ISAMO2( PRIME), UNIT=(2314,2), 
// DCB=( DSORG=IS,BLKSIZE=1000 ), SPACE=(CYL,(10)), 

// VOLUME=SER=( 444444 ,555555 ), DISP=( NEW, KEEP ) 


/* 
The control statements are discussed below: 
e EXEC specifies the program name and the COPY operation. 


e SYSUT1 DD defines an indexed-sequential input data set, which resides on 
two 2314 volumes. 


e SYSUT2 DD defines the output data set index area; the index and prime areas 
are Separated. 


e DD1 DD defines the output data set prime area. Ten cylinders are allocated 
for the prime area on each of the two 2314 volumes. 


In this example, indexed-sequential input is to be converted into a sequential data 
set; the output is to be placed on a 9-track tape volume. 


The example follows: 


J / STEP | JOB O9#770,SMITH 

Jf EXEC PGM=IEBISAM, PARM=UNLOAD 

//SYSPRINT DD SY SOUTHA 

Z/SYTSUT DD DSNAME=INDSEQO, UNIT=2314,DISP=(OLD,KEEP), 
// VOLUME=SER=111112,DCB=( DSORG=IS ) 

//SYSUT2 DD DSNAME=UNLDSET, UNIT=2400,LABEL=(,SL), 

// DISP=( ,KEEP ), VOLUME=SER=001234, 

// DCB=( RECFM=FB, LRECL=80, BLKSIZE=640 ) 

/* 


The control statements are discussed below: 
e EXEC specifies the program name and the UNLOAD operation. 


e SYSUT1 DD defines the indexed-sequential input data set, which resides on a 
2314 volume. 


e SYSUT2 DD defines the unloaded output data set. The data set consists of a 
fixed-blocked records, and is to reside as the first or only data set on a 9-track 
tape volume. The data set is to be written at a density of 800 bits per inch. 


In this example, indexed-sequential input is to be converted into a sequential data 
set and placed on a 7-track, tape volume. 
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The example follows: 


//STEPA JOB -099-770.5M1 7TH 

Ji EXEC PGM=IEBISAM, PARM=UNLOAD 

//SYSPRINT DD SYSOUT=A 

FF SLSUT DD DSNAME=INDSEQ, UNI T=2314,DISP=(OLD,KEEP), 
// VOLUME=SER=111112,DCB=( DSORG=IS ) 

J /#SYSUT2 DD DSNAME=UNLDSET,UNIT=2400-2,LABEL=(2,SL), 
// VOLUME=SER=001234,DCB=( DEN=2,RECFM=FB, 

// LRECL=80, BLKSIZE=1040, TRTCH=C ),DISP=( ,KEEP ) 

/* 


The control statements are discussed below: 
e EXEC specifies the program name and the UNLOAD operation. 


e SYSUTI DD defines the input data set, which is an indexed-sequential data 
set. The data set resides on a 2314 volume. 


e SYSUT2 DD defines the unloaded output data set. The data set consists of 
fixed-blocked records, and is to reside as the second data set on a 7-track tape 
volume. The data set is to be written at a density of 800 bits per inch. 


In this example, an unloaded data set is to be converted to the form of the 
original indexed-sequential data set. 


The example follows: 


//STEPA JOB 09#770,SMITH 

// EXEC PGM=IEBISAM, PARM=LOAD 

//SYSPRINT DD  SYSOUT=A 

//SYSUT1 DD  DSNAME=UNLDSET,UNIT=2400, LABEL=(2,SL), 

// DISP=( OLD,KEEP ), VOLUME=SER=001234 

//SYSUT2 DD  DSNAME=INDSEQ,DISP=( ,KEEP),DCB=(DSORG=IS), 
// SPACE=(CYL,(1)),VOLUME=SER=111112,UNIT=2314 

/* 


The control statements are discussed below: 
e EXEC specifies the program name and the LOAD operation. 


e SYSUT1 DD defines the input data set, which is a sequential (unloaded) data 
set. The data set is the second data set on a 9-track tape volume. 


¢ SYSUT2 DD defines the output data set, which is an indexed-sequential data 
set. One cylinder of space is allocated for the data set on a 2314 volume. 


In this example, the logical records of an indexed-sequential data set are to be 
printed on a system output device. 


The example follows: 


//PRINT JOB 09#770,SMITH 

EXEC PGM=IEBISAM,PARM='PRINTL,N' 
//SYSPRINT DD SYSOUT=A 
f/SYSUT] DD DSNAME=ISAMO03,UNIT=2314,DISP=OLD, 
// VOLUME=SER=222222 ,DCB=( DSORG=IS ) 
J (/SYSUT2Z DD SYSOUT=A 
/* 


The control statements are discussed below: 


EXEC specifies the program name and the PRINTL operation. The output 
records are not to be converted to hexadecimal prior to printing. 


SYSUT1 DD defines the input data set, which resides on a 2314 volume. 


SYSUT2 DD defines the output data set. A logical record length (LRECL) of 
121 bytes is assumed. 
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IEBPTPCH Program 


IEBPTPCH is a data set utility used to print or punch all, or selected portions, of 
a sequential or partitioned data set. Records can be printed or punched to meet 
either standard specifications or user specifications. (See “Introduction” for 
general data set utility information. ) 


The standard specifications are: 
e Each logical record begins on a new printed line or punched card. 


e Each printed line consists of 12 groups of 8 characters separated by 2 blanks. 
Each punched card contains up to 80 contiguous bytes of information. 
e Characters that cannot be printed appear as blanks. 


66999 


e When the input is blocked, each logical record is delimited by and each 


block is delimited by ‘‘**’’. 


User formats can be specified, provided that no output record exceeds the 
capability of the output device. 


IEBPTPCH provides optional editing facilities and exits for user routines that can 
be used to process labels or manipulate input or output records. 


JEBPTPCH can be used to: 

e Print or punch a sequential or partitioned data set in its entirety. 

e Print or punch selected members from a partitioned data set. 

e Print or punch selected records from a sequential or partitioned data set. 
e Print or punch the directory of a partitioned data set. 

e Print or punch an edited version of a sequential or partitioned data set. 


At the completion or termination of the program, the highest return code 
encountered within the program is passed to the calling program. 


Printing or Punching a Data Set 


IEBPTPCH can be used to print or punch a sequential data set or a partitioned 
data set in its entirety. Data to be printed or punched can be either hexadecimal 
or a character representation of valid alphameric bit configurations. For a print 
operation, packed-decimal data should be converted to unpacked-decimal or 
hexadecimal mode to ensure that all characters are printable. 


For a standard print operation, each logical record is printed in groups of eight 
characters. Each set of eight characters is separated from the next by two blanks. 
Up to 96 characters can be included on a printed line. (An edited output can be 
produced to omit the blank delimiters and print up to 144 characters per line.) 


Data from an input logical record is punched in contiguous columns in the 
punched card(s) representing that record. Sequence numbers can be created and 
placed in columns 73 through 80 of the punched cards. 


Printing or Punching Selected Members 


IEBPTPCH can be used: to print or punch selected members of a partitioned data 
set. Utility control statements are used to specify members to be printed or 
punched. 


IEBPTPCH Program 161 


Printing or Punching Selected Records 


IEBPTPCH can be used to print selected records from a sequential or partitioned 
data set. Utility control statements can be used to specify: 


e« The termination of a print or punch operation after a specified number of 
records has been printed or punched. 


e The printing or punching of every nth record. 


Printing or Punching a Partitioned Directory 


Printing or Punching an 


Input and Output 
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IEBPTPCH can be used to print or punch the contents of a partitioned directory. 
Each directory block is printed in groups of eight characters. If the directory is 
printed in hexadecimal representation, the first four printed characters of each 
directory block indicate the total number of used bytes in that block. For details 
of the format of the directory, see OS/VSI System Data Areas, SY28-0605, 
or OS/VS2 System Data Areas, SY28-0606. 


Data from a directory block is punched in contiguous columns in the punched 


cards representing that block. 


Edited Data Set 


IEBPTPCH can be used to print or punch an edited version of a sequential or a 
partitioned data set. Utility control statements can be used to specify editing 
information that applies to a record, a group of records, selected groups of 
records, or an entire member or data set. 


An edited data set is produced by: 
e Rearranging or omitting defined data fields within a record. 


e Converting data from packed-decimal to unpacked-decimal or from alphameric 
to hexadecimal representation. 


IEBPTPCH uses the following input: 


e An input data set, which contains the data that is to be printed or punched. 
The input data set can be either sequential or partitioned. 


e A control data set, which contains utility control statements. The control data 
set is required for each use of IEBPTPCH. 


IEBPTPCH produces the following output: 
e An output data set, which is the printed or punched data set. 


e A message data set, which contains informational messages (for example, the 
contents of the control statements) and any error messages. 


IEBPTPCH provides a return code to indicate the results of program execution. 
The return codes and their meanings are: 


¢ OO, which indicates successful completion. 


e 08, which indicates that a member specified for printing does not exist in the 
input data set. Processing continues with the next member. 


e 12, which indicates that an unrecoverable error occurred or that a user routine 
passed a return code of 12 to IEBPTPCH. The job step is terminated. 


e 16, which indicates that a user routine passed a return code of 16 to 
IEBPTPCH. The job step is terminated. 


Control 


IEBPTPCH is controlled by job control statements and utility control statements. 

The job control statements are required to execute or invoke the IEBPTPCH 

program and to define the data sets that are used and produced by the program. 
C The utility control statements are used to control the functions of IEBPTPCH. 


Job Control Statements 


Table 21 shows the job control statements necessary for using IEBPTPCH. 
Table 21. IEBPTPCH Job Control Statements 


Statement Use 
JOB Initiates the job step. 


EXEC Specifies the program name (PGM=IEBPTPCH) or, if the job control 
statementsreside in a procedure library, the procedure name. 


SYSPRINT DD Defines a sequential message data set. The data set can be written to a system 
output device, a tape volume, or a direct access device. 


SYSUT!I DD Defines a sequential or partitioned input data set. 
SYSUT2 DD Defines the output (printed or punched) data set. 


SYSIN DD Defines the control data set. The control data set normally resides in the input 
stream; however, it can be defined as a member in a partitioned data set. 


The input data set can contain fixed, variable, undefined, or variable-spanned 
records. 


Both the output data set and the message data set can be written to the system 
output device if it is a printer. Variable-spanned records are allowed only when 
the input is sequential. 


If the logical record length of the input records is such that the output would 
exceed the output record length, the utility divides the record into multiple lines 

{_ or cards in the case of standard printed output, standard punched output, or 
when the PREFORM operand was specified. Otherwise, only part of the input 
record is printed (a maximum of 144 characters) or punched (a maximum of 80 
characters). 


Restrictions 
e The SYSPRINT DD statement is required for each use of IEBPTPCH. 


| « The SYSUT2 DD statement is required every time IEBPTPCH is used. 


¢ The LRECL parameter, or, if no logical record length is specified, the 

BLKSIZE parameter, specifies the number of characters to be written per 
printed line or per punched card (this count includes a control character). The 
number of characters specified must be in the range of 2 through 145. The 

| default values for edited output lines are 121 characters per printed line and 
81 characters per punched card. The SYSUT2 data set can be blocked by 
specifying both the LRECL and the BLKSIZE parameters, in which case, 
block size must be a multiple of logical record length. 


°« The block size for the SYSPRINT data set must be a multiple of 121. The 
block size for the SYSIN data set must be a multiple of 80. Any blocking 
factor can be specified for these block sizes. 


e The SYSIN DD statement is required for each use of IEBPTPCH. 


« A partitioned directory to be printed must be defined as a sequential data set. 
Refer to ‘““PRINT Statement” below for details. 


IEBPTPCH Program 163 


Utility Control Statements 


IEBPTPCH is controlled by utility control statements. The control statements are 
shown in the order in which they must appear, as follows: 


e PRINT or PUNCH statement, which specifies that the data is to be either 
printed or punched. 


¢« TITLE statement, which specifies that a title is to precede the printed or 
punched data. 


e EXITS statement, which specifies that user routines are provided. 


e MEMBER statement, which specifies that the input is a partitioned data set 
and that a selected member is to be printed or punched. 


¢ RECORD statement, which specifies whether editing is to be performed, that 
is, records are to be printed or punched to non-standard specifications. 


e LABELS statement, which specifies whether user labels are to be treated as 
data. 


The control statements are included in the control data set, as required. Any 
number of MEMBER and RECORD statements can be included in a job step. 


PRINT Statement 
The PRINT statement is used to initiate the IEBPTPCH operation. If this is a 
print operation, PRINT must be the first statement in the control data set. 

The format of the PRINT statement is: 


iy OTe, A o ee BY 7 bs 


where: 

PREFORM= 
specifies that a control character is provided as the first character of each 
record to be printed. The control characters are used to control the spacing, 
number of lines per page, and page ejection. If an error occurs, the print 
Operation is terminated. If PREFORM is coded, except for syntax checking, 
any additional PRINT operands and all other control statements except 
LABELS statements are ignored. PREFORM must not be used for printing 
data sets with VS or VBS records longer than 32K bytes. These values can be 
coded. 
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specifies that an ASA control character is provided as the first character of 
each record to be printed. If the input record length exceeds the output 
record length, the utility uses the ASA character for printing the first line, 
with a single space character on all subsequent lines of the record. 


M 
specifies that a machine-code control character is provided as the first 
character of each record to be printed. If the input record length exceeds 
the output record length, the utility prints all lines of the record with a 
print-skip-one-line character until the last line of the record, which will 
contain the actual character provided as input. 


TYPORG= 
specifies the organization of the input data set. If TYPORG is omitted, 
sequential organization is assumed. These values can be coded: 


PS 
specifies that the input data set is organized sequentially. 


PO 
specifies that the input data set is partitioned. 


TOTCONV= 
specifies the representation of data to be printed. TOTCONV can be 
overridden by any user specifications (RECORD statements) that pertain to 
the same data. These values can be coded: 


XE 
specifies that data is to be printed in 2-character-per-byte hexadecimal 
representation (for example, C3 40 F4 F6). If XE is not specified, data is 
printed in 1-character-per-byte alphameric representation. The above 
example would appear as C 46. 


PZ 
specifies that data (packed-decimal mode) is to be converted to 
unpacked-decimal mode. If TOTCONYV is omitted, data is not converted. 


CNTRL= n 
specifies a control character for the output device that indicates line spacing, 
as follows: 1 indicates single spacing; 2 indicates double spacing; and 3 
indicates triple spacing. If CNTRL is omitted, 1 is assumed. 


STRTAFT= n 
specifies, for sequential data sets, the number of logical records (physical 
blocks in the case of VS or VBS type records longer than 32K bytes) to be 
skipped before printing begins. For partitioned data sets, STRTAFT=n 
specifies the number of logical records (physical blocks in the case of VS or 
VBS type records longer than 32K bytes) to be skipped in each member 
before printing begins. The n value must not exceed 32,767. If STRTAFT is 
specified and RECORD statements are present, the first RECORD statement 
of a member describes the format of the first logical record to be printed. 


STOPAFT= n 
specifies, for sequential data sets, the number of logical records (or physical 
blocks in the case of VS or VBS records longer than 32K bytes) to be printed. 
For partitioned data sets, this specifies the number of logical records (or 
physical blocks in the case of VS or VBS records longer than 32K bytes) to 
be printed in each member to be processed. The n value must not exceed 
32,767. If STOPAFT is specified and RECORD statements are present, the 
Operation is terminated when the STOPAFT count is satisfied or at the end of 
the first record group, whichever occurs first. 
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SKIP= n 
specifies that every nth record (or physical block in the case of VS or VBS 
records longer than 32K bytes) is to be printed. If SKIP is omitted, successive 
logical records are printed. 


MAXNAME®= n 
specifies a number no less than the total number of subsequent MEMBER 
statements. If MAXNAME is omitted when there is a MEMBER statement 
present, the print request is terminated. 


MAXFLDS= n 
specifies a number no less than the total number of FIELD parameters 
appearing in subsequent RECORD statements. If MAXFLDS is omitted when 
there is a FIELD parameter present, the print request is terminated. 


MAXGPS= n 
specifies a number no less than the total number of IDENT parameters 
appearing in subsequent RECORD statements. If MAXGPS is omitted when 
there is an IDENT parameter present, the print request is terminated. 


MAXLITS= n 
specifies a number no less than the total number of characters contained in 
the IDENT literals of subsequent RECORD statements. If MAXLITS is 
omitted when there is a literal present, the print request is terminated. 


INITPG=n 
specifies the initial page number; the pages are numbered sequentially 
thereafter. If INITPG is omitted, 1 is assumed. 


MAXLINE= n 
specifies the maximum number of lines to a printed page. Spaces, titles, and 
subtitles are included in this number. If MAXLINE is omitted, 60 is assumed. 


PUNCH Statement 


The PUNCH statement is used to initiate the IEBPTPCH operation. If this is a 
punch operation, PUNCH must be the first statement in the control data set. 


The format of the PUNCH statement is: 
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where: 


PREFORM= 
specifies that a control character is provided as the first character of each 
record to be punched. The control characters are used to select a stacker. If 
an error is discovered, the punch operation is terminated. If PREFORM is 
coded, except for syntax checking, any additional PUNCH operands and all 
other control statements except LABELS statements are ignored. PREFORM 
must not be used for punching data sets with VS or VBS records longer than 
32K bytes. These values can be coded: 


A 
specifies that an ASA control character is provided as the first character of 
each record to be punched. If the input record length exceeds the output 
record length, the utility duplicates the ASA character on each output card 
of the record. 


M 
specifies that a machine-code control character is provided as the first 
character of each record to be punched. If the input record length exceeds 
the output record length, the utility duplicates the machine control character 
on each output card of the record. 


TYPORG= 
specifies the organization of the input data set. If TYPORG is omitted, 
sequential organization is assumed. These values can be coded: 


PS 
specifies that the input data set is organized sequentially. 


PO 
specifies that the input data set is partitioned. 


TOTCONV= 
specifies the representation of data to be punched. TOTCONV can be 
overridden by any user specifications (RECORD statements) that pertain to 
the same data. These values can be coded: 


XE 
specifies that data is to be punched in 2-character-per-byte hexadecimal 
representation (for example, C3 40 F4 F6). If XE is not specified, data is 
punched in 1-character-per-byte alphameric representation. The above 
example would appear as C 46. 


PZ 
specifies that data (packed decimal mode) is to be converted to 
unpacked-decimal mode. If TOTCONYV is omitted, data is not converted. 


CNTRL= n 
specifies a control character for the output device that is used to select the 
stacker, as follows: 1 indicates the first stacker and 2 indicates the second 
stacker. If CNTRL is omitted, | is assumed. 


STRTAFT= n 
specifies, for sequential data sets, the number of logical records (physical 
blocks in the case of VS or VBS type records longer than 32K bytes) to be 
skipped before punching begins. For partitioned data sets, STRTAFT= 7 
specifies the number of logical records (physical blocks in the case of VS or 
VBS type records longer than 32K bytes) to be skipped in each member 
before punching begins. The n value must not exceed 32,767. If STRTAFT is 
specified and RECORD statements are present, the first RECORD statement 
of a member describes the format of the first logical record to be punched. 
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STOPAFT= n 
specifies, for sequential data sets, the number of logical records (or physical 
blocks in the case of VS or VBS records longer than 32K bytes) to be 
punched. For partitioned data sets, this specifies the number of logical records 
(or physical blocks in the case of VS or VBS records longer than 32K bytes) 
to be punched in each member to be processed. The n value must not exceed 
32,767. If STOPAFT is specified and RECORD statements are present, the 
operation is terminated when the STOPAFT count is satisfied or at the end of 
the first record group, whichever occurs first. 


SKIP= n 
specifies that every nth record (or physical block in the case of VS or VBS 
records longer than 32K bytes) is to be punched. If SKIP is omitted, 
successive logical records are punched. 


MAXNAME= n 
specifies a number no less than the total number of subsequent MEMBER 
statements. If MAXNAME is omitted when there is a MEMBER statement 
present, the punch request is terminated. 


MAXFLDS= n 
specifies a number no less than the total number of FIELD parameters 
appearing in subsequent RECORD statements. If MAXFLDS is omitted when 
there is a FIELD parameter present, the punch request is terminated. 


MAXGPS= n 
specifies a number no less than the total number of IDENT parameters 
appearing in subsequent RECORD statements. If MAXGPS is omitted when 
there is an IDENT parameter present, the punch request is terminated. 


MAXLITS= n 
specifies a number no less than the total number of characters contained in 
the IDENT literals of subsequent RECORD statements. If MAXLITS is 
omitted when there is a literal present, the punch request is terminated. 


CDSEQ= n 
specifies the initial sequence number of a deck of punched cards. This value 
must be contained in columns 73 through 80. Sequence numbering is 
initialized for each member of a partitioned data set. If CDSEQ is omitted, the 
cards are not numbered. If the value of n is zero, OOOO00000 is assumed as a 
starting sequence number. 


CDINCRE= n 
specifies the increment to be used in generating sequence numbers. If 
CDINCR is omitted and CDSEQ is coded, 10 is assumed as an increment 
value for sequence numbering. 


The TITLE statement is used to request title and subtitle records. Two TITLE 
statements can be included for each use of IEBPTPCH. A first TITLE statement 
defines the title, and a second defines the subtitle. The TITLE statement, if 
included, must immediately follow the PRINT or PUNCH statement in the 
control data set. 


The format of the TITLE statement is: 


sf i 5 ot is A / ! ; wi : i. ee > “| q I = al, oie ry! & ov We ye SAS . i, Dee Cs fay 
‘[name] TITLE ITEM= (‘title*[, output-location}} 
7 . i. ‘ ; 4 ’ “eel . at” - - ' Pie 4 \ sth rs 


where: 


ITEM= 
specifies title or subtitle information. The values that can be coded are: 


* title’ 
specifies the title or subtitle literal (maximum length of 40 bytes), enclosed 
in apostrophes. If the literal contains apostrophes, each apostrophe must be 
written as two consecutive apostrophes. 


output-location 
| specifies the starting position at which the literal for this item is to be 
placed in the output record. If output-location is not specified, 1 is 
assumed. The specified title may not exceed the output logical record 
length minus 1. 


EXITS Statement 


The EXITS statement is used to identify exit routines supplied by the user. Exits 
to label processing routines are ignored if the input data set is partitioned. 
Linkage to and from user routines are discussed in ‘‘Appendix A: Exit Routine 
Linkage.” 


The EXITS statement, if included, must immediately follow any TITLE statement 
or follow the PRINT or PUNCH statement. 


The format of the EXITS statement is: 


[ Jabel] EXITS [INHDR= routinename | 
[INTLR= routinename | 
[INREC= routinename | 
[OUTREC= routinename | 


where: 


INHDR=  routinename 


specifies the symbolic name of a routine that processes user input header 
labels. 


INTLR= routinename 


specifies the symbolic name of a routine that processes user input trailer 
labels. 


INREC= routinename 
specifies the symbolic name of a routine that manipulates each logical record 
(or physical block in the case of VS or VBS records longer than 32K bytes) 
before it is processed. 


OUTREC= routinename 
specifies the symbolic name of a routine that manipulates each logical record 
(or physical block in the case of VS or VBS records longer than 32K bytes) 
before it is printed or punched. When standard specifications are used, this 
exit is not available. 


MEMBER Statement 


The MEMBER statement is used to identify members to be printed or punched. 
All RECORD statements that follow a MEMBER statement ‘pertain to the 
member indicated in that MEMBER statement only. If no RECORD statement is 
used, the member is processed to standard specifications. 


If no MEMBER statement appears, and a partitioned data set is being processed, 
all members of the data set are printed or punched. Any number of MEMBER 
statements can be included in a job step. 
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The format of the MEMBER statement is: 


where: 
NAME= 
specifies a member to be printed or punched. These values can be coded: 


membername 
specifies a member; by its member name. 


aliasname 
specifies a member by its alias. 


If the NAME parameter is specified in the MEMBER statement, MAXNAME 
must be specified in a PRINT or PUNCH statement. 


The RECORD statement is used to define a group of records—called a record 
group —that is to be printed or punched to the user’s specifications. A record 
group consists of any number of records to be edited identically. 


If no RECORD statements appear, the entire data set, or named member, is 
printed or punched to standard specifications. If a RECORD statement is used, 
all data following the record group it defines (within a partitioned member or 
within an entire sequential data set) must be defined with other RECORD 
statements. Any number of RECORD statements can be included in a job step. 


The format of the RECORD statement is: 


i 


where: 


IDENT= 
identifies the last record of the record group to which the FIELD parameters 
apply.If IDENT is omitted and STOPAFT is not included with the PRINT or 
PUNCH statement, record processing halts after the last record in the data 
set. If IDENT is omitted and STOPAFT is included with the PRINT or 
PUNCH statement, record processing halts when the STOPAFT count is 
satisfied or after the last record of the data set is processed, whichever occurs 
first. The values that can be coded are: 


length 
specifies the length (in bytes) of the field that contains the identifying name 
in the input records. The length cannot exceed eight bytes. 


‘name’ 
specifies the exact literal that identifies the last record of a record group. If 
the literal contains apostrophes, each must be written as two consecutive 
apostrophes. 


input-location 


specifies the starting location of the field that contains the identifying name 
in the input records. 


J 


FIELD= 
specifies field-processing and editing information. These values can be coded: 


length 
specifies the length (in bytes) of the input field to be processed. The sum 
of the field lengths may not exceed the logical output record length minus 
1. 


input-location 
specifies the starting byte of the input field to be processed. If 
input-location is not specified, 1 is assumed. 


conversion 
specifies a two-byte code that indicates the type of conversion to be 
performed on this field before it is printed or punched. If conversion is not 
specified, the field is moved to the output area without change. The values 
that can be coded are: 


PZ 
specifies that data (packed decimal) is to be converted to unpacked 
decimal data. 


XE 
specifies that data (alphameric) is to be converted to hexadecimal data. 


output-location 
specifies the starting location of this field in the output records. If 
output-location is not specified, 1 is assumed. Unspecified fields in the 
output records appear as blanks in the printed or punched output. Data that 
exceeds the SYSUT72 printer or punch size is not printed or punched. The 
specified fields may not exceed the logical output record length minus 1. 


A RECORD statement referring to a partitioned data set for which no members 
have been named need contain only FIELD parameters. These are applied to the 
records in all members of the data set. 


If a FIELD parameter is included in the RECORD statement, MAXFLDS must 
be specified in the PRINT or PUNCH statement. 


If an IDENT parameter is included in the RECORD statement, MAXGPS must 
be specified in the PRINT or PUNCH statement. 


LABELS Statement 


The LABELS statement specifies whether user labels are to be treated as data. 
For a detailed discussion of this option, refer to ‘“‘Processing User Labels as 
Data,” in ‘‘Appendix E: Processing User Labels.” 


The format of the LABELS statement is: 
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where: 


DATA= 


specifies whether user labels are to be treated as data. The values that can be 
coded are: 


YES 


specifies that any user labels that are not rejected by a user’s label 
processing routine are to be treated as data. Processing of labels as data 


stops in compliance with standard return codes. If no value is entered, YES 


is assumed. 


NO 


specifies that user labels are not to be treated as data. 


ALL 


specifies that user labels are to be treated as data regardless of any return 
code.A return code of 16 causes the utility to complete the processing of 
the remainder of the group of user labels and to terminate the job step. 


ONLY 


specifies that only user header labels are to be treated as data. User header 


labels are processed as data regardless of any return code. The job 
terminates upon return from the OPEN routine. 


If more than one valid LABELS statement is included, all but the last LABELS 


statement are ignored. 


The following examples illustrate some of the uses of IEBPTPCH. Table 22 can 
be used as a quick reference guide to IEBPTPCH examples. The numbers in the 
“Example” column point to the examples that follow. 


Table 22. IEBPTPCH Example Directory 


Operation 
PRINT 


PUNCH 


PRINT 


PRINT 


PRINT 


PUNCH 


PRINT 


PUNCH 


PRINT 


Data Set 


Organization Devices 


Sequential 


Sequential 


Partitioned 


Partitioned 


Sequential 


Sequential 


Sequential, 
Partitioned 


Sequential 


Sequential 


9-track tape, 
System printer 


7-track tape, 
Card Reader 


3330 Drum, 
System printer 


2314 Disk, 
System printer 


9-track tape, 
System printer 


2314 Disk, 
Card Reader 
Punch 


2314 Disk, 
System printer 


Card Reader, 
Card Read 
Punch 


2314 Disk, 
System printer 


Comments 


Standard format. Conversion to 
hexadecimal. 


Standard format. Conversion to 
hexadecimal. 


Standard format. Conversion to 
hexadecimal. Ten records from 
each member are to be printed. 


Standard format. Conversion to 
hexadecimal. Two members are 
to be printed. 


User-specified format. Input 
data set is the second data set 
on the volume. 


User-specified format. Sequence 
numbers are to be assigned and 
punched. 


Standard format. Conversion to 
hexadecimal. 


Standard format. Control data 
set is a member in a cataloged 
partitioned data set. 


User-specified format. User 


routines are provided. Processing 


ends after first record group is 
printed. 


Example 


J 


L 
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In this example, a sequential data set is to be printed according to standard 
specifications. The input data set resides on a 9-track tape volume, originally 
written at a density of 800 bits per inch. The printed output is to be converted to 
hexadecimal. 


The example follows: 


//PRINT JOB 09#660,SMITH 
// EXEC PGM=IEBPTPCH 
//SYSPRINT DD SYSOUT=A 
//SYSUT1 DD  UNIT=2400,LABEL=( ,NL), VOLUME=SER=001234, 
// DISP=(OLD,KEEP ),DCB=( RECFM=U, BLKSIZE=2000 ) 
//SYSUT2 DD SYSOUT=A 
//SYSIN DD * 
PRINT  TOTCONV=XE 
TITLE ITEM=('PRINT SEQ DATA SET WITH CONV TO HEX',10) 
/ * 


The control statements are discussed below. 


e SYSUT1 DD defines the input data set. The data set contains undefined 
records; no record is larger than 2,000 bytes. 


e SYSUT2 DD defines the output data set. The data set is written to the system 
output device (printer assumed). Each printed line contains up to 12 groups (8 
characters each) of hexadecimal information. Each record begins a new line of 
printed output. 


e SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PRINT and TITLE statements. 


e PRINT initiates the print operation and specifies conversion from alphameric 
to hexadecimal representation. 


e TITLE specifies a title to be placed beginning in column 10 of the printed 
output. The title is not converted to hexadecimal. 


In this example, a sequential data set is to be punched according to standard 
specifications. The input data set resides on a 7-track tape volume, originally 
written at a density of 556 bits per inch. The punched output is converted to 
hexadecimal. 


The example follows: 


//PUNCHSET JOB 09#660,SMITH 
Lf EXEC. -PGM=LTEBPIPCH 
//SYSPRINT DD SYSOUT=A 
J/SYSUT | DD DSNAME=INSET, UNIT=2400-2, VOLUME=SER=001234, 
// LABEL=( ,NL),DISP=( OLD, KEEP ),DCB=(DEN=1, 
// RECFM=FB,LRECL=80, BLKSIZE=2000, TRTCH=C ) 
ff SYSUT2Z DD UNIT=2540-2 
J/SYSIN DD * 
PUNCH TOTCONV=XE 
sigs Sea Bs ITEM=('PUNCH SEO DATA SET WITH CONV TO HEX', 10°) 
/* 


The control statements are discussed below: 


¢ SYSUT1 DD defines the input data set. The data set contains 80-byte, 
fixed-blocked records. 


« SYSUT2 DD defines the output data set. The data set is to be punched by an 
IBM 2540-2 Card Read Punch (punch feed). Each record from the input data 
set is represented by two punched cards. 
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e SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PUNCH and TITLE statements. 


e PUNCH initiates the punch operation and specifies conversion from 
alphameric to hexadecimal representation. 


e TITLE specifies a title to be placed beginning in column 10. The title is not 
converted to hexadecimal. 


In this example, a partitioned data set (ten records from each member) is to be 
printed according to standard specifications. The input data set resides on a 3330 
volume. The printed output is converted to hexadecimal. 


The example follows: 


//PRINTPDS JOB O0O9#660,SMITH 
ff EXEC PGM=IEBPTPCH 
//SYSPRINT DD SYSOUT=A 
J7 SYSUT) DD DSNAME=PDS , UNIT=3330,DISP=(OLD,KEEP), 
// VOLUME=SER=111112,DCB=( RECFM=U,BLKSIZE=3625 ) 
J fSYSUT2 DD SYSOUT=A 
ff SYSIN DD * 
PRINT TOTCONV=XE , TY PORG=PO , STOPAF'T=10 
TITLE TTEM=("PRINT PDS = 10° RECS: EACH .MEM* 5:20 ) 


/* 
The control statements are discussed below: 


e SYSUT1 DD defines the input data set. The data set contains undefined 
records; no record is larger than 3,625 bytes. 


e SYSUT2 DD defines the output data set on the system output device (printer 
assumed). Each printed line contains up to 12 groups (8 characters each) of 
hexadecimal information. Each record begins a new line of printed output. The 
size of the record determines how many lines of printed output are required 
per record. 


e SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PRINT and TITLE statements. 


e PRINT initiates the print operation, specifies conversion from alphameric to 
hexadecimal representation, indicates that the input data set is partitioned, and 
specifies that ten records from each member are to be printed. 


e TITLE specifies a title to be placed beginning in column 20 of the printed 
output. The title is not converted to hexadecimal. 


In this example, two partitioned members are to be printed according to standard 
specifications. The input data set resides on a 2314 volume. The printed output is 
to be converted to hexadecimal. 


L 
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The example follows: 


//PRNTMEMS JOB 


09#660,SMITH 


ty EXEC PGM=IEBPTPCH 


//SYSPRINT DD 
J7SLSUT DD 


SYSOUT=A 
DSNAME=PDS ,DISP=( OLD, KEEP ), VOLUME=SER=111112, 


// DCB=(RECFM=F, LRECL=80,BLKSIZE=80 ), UNIT=2314 


JI SY SUT2 DD 


JL SLSIN DD 
PRINT 
aE 

MEMBER 
MEMBER 
/* 


SYSOUT=A 

* 

TYPORG=PO , TOTCONV=XE, MAXNAME=2 

ITEM=('PRINT TWO MEMBS WITH CONV TO HEX',10) 
NAME=MEMBER1 

NAME=MEMBER2 


The control statements are discussed below: 


e SYSUT1 DD defines the input data set. The data set contains 80-byte, fixed 


records. 


e SYSUT2 DD defines the output data set on the system output device (printer 
assumed). Each printed line contains up to 12 groups (8 characters each) of 
hexadecimal information. Each record begins a new line of printed output. 


e SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains PRINT, TITLE, and MEMBER statements. 


e PRINT initiates the print operation, indicates that the input data set is 
partitioned, specifies conversion from alphameric to hexadecimal 
representation, and indicates that two MEMBER statements appear in the 


control data set. 


e TITLE specifies a title to be placed beginning in column 10 of the printed 
output. The title is not converted to hexadecimal. 


¢ MEMBER specifies the member names of the members to be printed. 


In this example, a sequential data set is to be printed according to user 
specifications. The input data set is the second data set on a 9-track tape volume. 
The data set was originally written at a density of 800 bits per inch. 


The example follows: 


//PTNONSTD JOB 


O9#660,SMITH 


id EXEC PGM=IEBPTPCH 


//SYSPRINT DD 
//SYSUT1 DD 


SYSOUT=A 
DSNAME=SEQSET, UNIT=2400, LABEL=(2,SUL), 


// DISP=(OLD,KEEP ), VOLUME=SER=001234, 
// DCB=(RECFM=FB,LRECL=80, BLKSIZE=2000 ) 


JI SYSUT2 DD 


//SYSIN DD 
PRINT 
RECORD 
LABELS 
BALTES 
/* 


SYSOUT=A 

* 

MAXFLDS=1 

FTELD=( 80 ) 

DATA=YES 

TINHDR=HDRIN, INTLR=TRLIN 


The control statements are discussed below: 


e SYSUT1 DD defines the input data set. The data set contains 80-byte, 
fixed-blocked records. 


e SYSUT2 DD defines the output data set on the system output device (printer 
assumed). Each printed line contains 80 contiguous characters (one record) of 


information. 
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¢ SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PRINT, RECORD, EXITS, and LABELS 
statements. 


¢ PRINT initiates the print operation and indicates that one FIELD parameter is 
included in a subsequent RECORD statement. 


¢ RECORD indicates that each input record is to be processed in its entirety 
(80 bytes). Each input record is printed in columns 1 through 80 on the 
printer. 


¢ LABELS specifies that user header and trailer labels are to be printed 
according to the return code issued by the user exits. 


¢« EXITS indicates that exits will be taken to user header-label and trailer-label 
processing routines when these labels are encountered on the SYSUT1 data 
set. 
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In this example, a sequential data set is to be punched according to user 
specifications. The input data set resides on a 2314 volume. 


The example follows: 


//PHSEQNO JOB 09#660,SMITH 
Tf EXEC PGM=IEBPTPCH 
//SYSPRINT DD SYSOUT=A 
//SYSUT1 DD  DSNAME=SEQSET,UNIT=2314, 
// NOLUME=SER=111112,DISP=(OLD,KEEP ), 
// DCB=( RECFM=FB,LRECL=80, BLKSIZE=2000 ) 
//SYSUT2 DD  DSNAME=PUNCHSET, UNIT=2540-2 
//SYSIN DD ¥ 
PUNCH  MAXFLDS=1,CDSEQ=00000000,CDINCR=20 
RECORD  FIELD=(72) 
LABELS DATA=ONLY 


/* 
The control statements are discussed below: 


¢ SYSUT1 DD defines the input data set. The data set contains 80-byte, 
fixed-blocked records. 


e SYSUT2 DD defines the output data set. The data set is to be punched by an 
IBM 2540-2 Card Read Punch (punch feed). Each record from the input data 
Set is represented by one punched card. 


e SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PUNCH, RECORD, and LABELS statements. 


e PUNCH initiates the punch operation, indicates that one FIELD parameter is 
included in a subsequent RECORD statement, and assigns a sequence number 
for the first punched card (OOOO0000) and an increment value for successive 
sequence numbers (20). Sequence numbers are placed in columns 73 through 
80 of the output records. 


¢ RECORD indicates that bytes 1 through 72 of the input records are to be 
punched. Bytes 73 through 80 of the input records are replaced by the new 
sequence numbers in the output card deck. 


« LABELS specifies that only user header labels are to be punched. 
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In this example, the directory of a partitioned data set is to be printed. The input 
data set resides on a 2314 volume. The printed output is to be converted to 
hexadecimal. 
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The example follows: 


//PRINTDIR JOB 09#660,SMITH 

j/ EXEC PGM=IEBPTPCH 

//SYSPRINT DD  SYSOUT=A 

//SYSUT1 DD  DSNAME=PDS,UNIT=2314, VOLUME=SER=111112, 

// LABEL=( ,SUL),DISP=(OLD,KEEP), 

// DCB=( RECFM=U, BLKSIZE=3625 ) 

//SYSUT2 DD  SYSOUT=A 

//SYSIN DD * 
PRINT  TYPORG=PS,TOTCONV=XE 
TITLE ITEM=('PRINT PARTITIONED DIRECTORY OF PDS',10) 
TITLE ITEM=('FIRST TWO BYTES SHOW NUM OF USED BYTES',10) 
LABELS DATA=NO 

/* 


The control statements are discussed below: 
e SYSUT1 DD defines the input data set (the partitioned directory). 


¢ SYSUT2 DD defines the output data set on the system output device (printer 
assumed). Each printed line contains up to 12 groups (8 characters each) of 
hexadecimal information. Six lines of print are required for each record. Each 
record begins a new line of printed output. 


¢ SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PRINT, TITLE, and LABELS statements. 


e PRINT initiates the print operation, indicates that the partitioned directory is 
organized sequentially, and specifies conversion from alphameric to 
hexadecimal representation. 


e The first TITLE statement specifies a title, which is not converted to 
hexadecimal. 


« The second TITLE statement specifies a subtitle, which is not converted to 
hexadecimal. 


« LABELS specifies that no user labels are to be printed. 


Note: Not all of the bytes in a directory block need contain data pertaining to 
the partitioned data set; unused bytes are sometimes used by the operating 
system as temporary work areas. The first four characters of printed output 
indicate how many bytes of the 256-byte block pertain to the partitioned data 
set. Any unused bytes occur in the latter portion of the directory block; they are 
not interspersed with the used bytes. 


In this example, a card deck containing valid punch card code or BCD is to be 
duplicated. The input card deck resides in the input stream. 


The example follows: 


/ / PUNCH JOB 09#660,SMITH 

// EXEC PGM=IEBPTPCH 

//SYSPRINT DD  SYSOUT=A 

//SYSIN DD DSNAME=PDSLIB( PNCHSTMT ),DISP=( OLD,KEEP ) 


PS (SUN2 DD UNIT=2540-2 
J£SYSUT) DD DATA 


(input card data set) 


is 
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The control statements are discussed below: 


SYSIN DD defines the control data set. The control data set contains a 
PUNCH statement and is defined as a member of the partitioned data set 
PDSLIB. (The data set is cataloged.) 


SYSUT2 DD defines the output data set. The data set is to be punched on an 
IBM 2540-2 Card Read Punch (punch feed). 


SYSUT1 DD defines the input card data set, which follows in the input 
stream. 


In this example, a record group is to be printed. A user routine is provided to 
manipulate output records before they are printed. 


The example follows: 


2: 


ff PRINT JOB O09#660,SMITH 


EXEC PGM=IEBPTPCH 


//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=SEQDS , UNIT=2314,DISP=(OLD,KEEP ), 
Jf TABEL=(, SUL); VOLUME=SER=11117 12; 

// DCB=( RECFM=FB, LRECL=80, BLKSIZE=2000 ) 

//SYSUT2 DD SYSOUT=A 

//SYSIN DD * 


/* 


PRINT MAXFLDS=2,MAXGPS=1,MAXLITS=6 , STOPAFT=32767 
TITLE ITEM=('TIMECONV-DEPT D06 JAN 10-17") 
EXITS OUTREC=NEWTIME, INHDR=HDRS, INTLR=TLRS 
RECORD  IDENT=(6,'498414',1), (Vc 
FIELD=(8,1,,10),FIELD=( 30,9,XE, 20) 
LABELS DATA=ALL, CONV=XE 


The control statements are discussed below: 


SYSUT1 DD defines the input data set. The data set resides on a 2314 
volume. 


SYSUT2 DD defines the output data set on the system output device (printer 
assumed). 


SYSIN DD defines the control data set, which follows in the input stream. The 
control data set contains the PRINT, TITLE, EXITS, and RECORD 
statements. 


The PRINT statement: (1) initializes the print operation, (2) indicates that 
two FIELD parameters are included in subsequent RECORD statements, (3) 
indicates that one IDENT parameter is included in a subsequent RECORD 
statement, (4) indicates that six literal characters are included in the 
subsequent IDENT parameter, and (5) indicates that processing is to be 
terminated after 32,767 records are processed or after the first record group is 
processed, whichever comes first. Because MAXLINE is omitted, 60 lines are 
printed on each page. 


TITLE specifies a title. 


EXITS specifies the name of a user routine (NEWTIME), which is used to 
manipulate output records before they are printed. 


RECORD defines the record group to be processed and indicates where 
information from the input records is placed in the output records. Bytes 1 
through 8 of the input records appear in columns 10 through 17 of the 
punched output, and bytes 9 through 38 are printed in hexadecimal 
representation and placed in columns 20 through 79. 


¢« LABELS specifies that all user header or trailer labels are to be printed 
regardless of any return code, except 16, issued by the user’s exit routine. It 
also indicates that the labels are to be converted from alphameric to 
hexadecimal representation. 
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IEBTCRIN Program 


Error Records 


IEBTCRIN is a data set utility used to read input from the IBM 2495 Tape 
Cartridge Reader (TCR), edit the data as specified by the user, and produce a 
sequentially organized output data set. (See “Introduction” for general data set 
utility information.) 


The input to IEBTCRIN is in the form of cartridges written by either the IBM 
Magnetic Tape SELECTRIC Typewriter (MTST) or the IBM 50 Magnetic Data 
Inscriber (MTDI). An input data set (one or more cartridges) must consist of 
either all MTST cartridges or all MTDI cartridges. 


IEBTCRIN can be used to construct records from the stream of data bytes read 
sequentially from the Tape Cartridge Reader. The user has the option of gaining 
temporary control (via a user-supplied exit routine) to process each logical 
record. 


When MTDI input is edited, IEBTCRIN maintains information about each record 
as it is being edited. This information is summarized in the Error Description 
Word (EDW) which is described below. When the EDW contains a non-zero 
value in either the level status (byte 0) or the type status (byte 1), the record is 
considered an error record by the program and the EDW is appended to the start 
of the record to aid the user in analyzing the error. 


If a record is found to be in error, the record is passed to the user error exit 
routine if one is specified. If an error exit is not specified, the action to be taken 
is determined by the option specified in a utility control statement. 


When either MTST input or MTDI input without editing is specified, the only 
error that can be recognized is a record containing one or more permanent data 
checks. The data check bytes are replaced as described in a utility control 
statement. The record is considered an error record, but because a data check is 
the only error that can occur, no EDW is appended to the error record. 


Error Description Word (EDW) 


Level Status (Byte 0) 


The Error Description Word (EDW) consists of four bytes that are appended to 
the start of an error record. 


The error description word is in EBCDIC format; for example, a 2 is represented 
as X‘F2’ and a C is represented as X‘C3’. The information provided in each of 
the four bytes of the EDW is discussed below. 


The level-status indicator identifies error records that result from inter-record 
dependency that cannot be identified in the type-status byte. 


The level status is presented with each error record and has a value of: 


¢ O, for any error record that will not cause questionable data in following 
records. A non-zero type status accompanies this byte. 


¢ 1, for any error record that may cause questionable data in following records, 
and for which the level status of the previous record was 0. 
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Type Status (Byte 1) 
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e 2, for any error record that contains questionable data because the error level 
of the preceding record was 1 or 2, or for any error record that may cause 
questionable data in the following records and for which the level status of the 
previous record was 1 or 2. 


A level status of other than 0 is presented with error records resulting from the 
following: 


e The start-of-record (SOR) location has a character defined as an error. 


¢ The record contains two or more data-check bytes side by side. These may 
have been an SOR and EOR. 


¢ The record is longer than the user-specified maximum length record. 


¢ The length of the record is not equal to the length of the first valid record of 
the same program level encountered on this cartridge. For this purpose, a valid 
record is one that contains no errors as identified in the type status, with the 
possible exception of being shorter than the user-specified minimum length. 


e The record has a data-duplication dependency on a previous record with one 
of the above errors. 


The level status is set to OQ when IEBTCRIN encounters: (1) a record without 
one of the previous errors, (2) a canceled record, or (3) the first record of a 
cartridge. 


The type-status indicator identifies records in error because of SOR, EOR, 
length, field, or data-check error conditions. 


The type status is presented with each error record and has a value of: 


e 0, for any record that contains none of the following identifiable errors, but ) 
contains questionable data due to a non-zero level status. (See ‘‘Level Status” 
earlier in this chapter.) 


e 1, for any record that has: (1) an SOR character of other than P1 through P8 
or a GS code, (2) an EOR character of other than a VOK code for records 
when the user specified a record-verification check, or (3) an EOR character 
of other than a VOK or RM code for records when the user specified no 
record-verification check. 


e 2, for any record that has an incorrect length because it is: (1) longer than the 
user-specified maximum, (2) shorter than the user-specified minimum, or (3) 
not equal to the length of the first valid record of the same program level 
encountered on this cartridge. 


e 4, for any record that has a field error. A field error occurs when duplication 
or left-zero justification functions did not occur in a field due to an error 
condition. See ‘““MTDI Editing Criteria” below. 


e 8, for any record that has a permanent data check error. 


The type-status indicator can also have values of 3, 5, 6, 7, 9, A, B, C, D, E, 
and F. These values indicate a combination of SOR, EOR, length, field, and 
data-check errors. For example, a value of A indicates a record with a data-check 
error (8) as well as an incorrect length (2). 


Start-of-Record (Byte 2) 


This byte contains an indication of the start-of-record (SOR) character associated 
with this record. The SOR character can be 1 through 8, where 1 indicates P1, 2 
( indicates P2, etc., or E, which indicates that the SOR character is in error. 


End-of-Record (Byte 3) 


This byte contains an indication of the end-of-record (EOR) character associated 
with this record. The EOR character can be: U, which indicates an unverified 
record; V, which indicates a verified record; or E, which indicates that the EOR 
character is in error. 


Sample Error Records 


Figure 33 shows a stream of data bytes read sequentially from the tape cartridge 
reader. 


Figure 34 shows the records constructed by IEBTCRIN from the input records 
shown in Figure 33. These records show some of the errors that can occur during 
processing and their effect on the Error Description Word. The following 
parameters were specified for these records: 


12 
TCRGENTYPE=MTDI,EDIT=EDITR, VERCHK=VOKCHK, ( ( C 
MAXLN=50,REPLACE=X‘5B’ 


Vv 
111372 RECORD NUMBER 1A0 
K 


* DDDDDDDDDDDDDDD DV 
*111378UUUUUUUUUUUUUUU 200 


1 * PPPPPPPPPPPPPPP:. PK 


DDDDDDDDDDDDDDD DV * V 
35798 7UUUUUUUUUUUUUUU 300 358977 REC*RD NUMBER 4AO 
1 PPPPPPPPPPPPPPP PK 1 * K 


DDDDDDDDDDDDDDD DV 
3584 36UUUUUUUUUUUUUUU6U0 
PPPPPPPPPPPPPPP PK 


P 
358436 RECORD NUMBER 5 
1 


V 
998865 RECORD NUMBER 7A MAXIMUM 00001430 IN WAREHOUSEO 


3 K 


P * VE 
367*82 RECORD NUMBER 8AO 
- KD 


Figure 33. Tape Cartridge Reader Data Stream 
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(Record 3) (Record 4 


— 


(Record 1) (Record 2 


V V 


P O O 
1111372 RECORD NUMBER 1AK $111378 RECORD NUMBER 2AK 


— 


V V 
O 


P P O 
1357987 RECORD NUMBER 3AK 1358977 REC$RD NUMBER 4AK 


~— 


(Record 6 


V 
R 


P O 
1358436 RECORD NUMBER 6$K 


(Record 7) (Record 8) 


P 
3998865 RECORD NUMBER 7A MAXIMUM 00001430 IN WAREH 


V 
O 
21EV| OUSEK 


(Record 9) S 


MAXLN ends here 
V (EOR Forced) 

Pp O 

1367$82 RECORD NUMBER 8AK 


Resulting Error 
Description Word 


Figure 34. Record Construction 


IEBTCRIN classifies records 2 through 9 in Figure 34 as error records. The 
records are classified, as follows: 


Record 1 is a valid record. It contains a program-level 1 code, and thus 
establishes the valid length for all program-level 1 records in this cartridge to 
be 25 bytes. 


Record 2 has a data check in the SOR location. Level status is set to 1 
because the SOR location might have contained a cancel code that would 
cause any data duplicated on the following record to be questionable. The 
type status (9) indicates the record has an incorrect SOR/EOR character (1) 
and a data check error (8). 


Record 3 contains no identifiable error, but contains questionable data because 
it requires duplication from the previous record, which had a level status of 1. 


Record 4 has a data check. Because it contained no DUP codes, the level 
status is set to 0. 


Record 5 is shorter than the first program-level 1 record on this cartridge 
(length error). This record also contains an RM code rather than a VOK code 
in the EOR location (VOKCHK was specified). Because IEBTCRIN cannot 
determine why the record is short, all data duplicated from this record is 
questionable; the level status is set to 1. The type status is set to 3 indicating 
an SOR/EOR error (1) and length error (2). 


Record 6 contains a DUP code that is beyond the last position of the 
preceding record. 


The seventh input record is longer than the maximum user-specified record 
length. Note that it is passed as two records. The first record (record 7) 
indicates an EOR error and a length error; the second (record 8) indicates an 
SOR error. Because record 7 is an error record, its length (SO bytes) is not 
established as the valid length for all program-level 3 records on this cartridge. 


J 


C 


MTDI Editing Criteria 


MTDI Editing Restrictions 


e Record 9 has a data check. Because it contained no DUP codes, the level 
Status is set to 0. 


The cartridges created on the IBM 50 Magnetic Data Inscriber contain a 
continuous stream of data bytes (that is, there are no interblock gaps). 
Therefore, when editing is specified, IEBTCRIN extracts records one at a time 
from the data stream. To accomplish this, IEBTCRIN scans for control codes 
written by MTDI. IEBTCRIN uses start-of-record (SOR) and end-of-record 
(EOR) locations to extract MTDI records from the input stream. 


The (SOR) location is defined as: 

e The location of the first character on a cartridge. 

e The location of the first character after the previous record’s (EOR) location. 
e The location of an SOR code. 

e The location of a GS code. 


The character in the SOR location is checked to determine if it is a valid 
start-of-record character. A P1 through P8, a cancel code, or a GS code are valid 
start-of-record characters; all others are invalid. 


The EOR location by priority sequence is: 


1. The same location as the SOR location, if the SOR character was a valid GS 
code. 


2. The location of the first encountered RM or VOK code if that location is 
within the length of the maximum user-specified record size. 


3. The location of any code preceding either a valid SOR code or the 
end-of-media code, if that location is within the length of the maximum 
user-specified record size. 


4. The location determined in 2 or 3, regardless of the maximum user-specified 
record size if the SOR location contains a cancel code. 


5. If one of the previous EOR locations cannot be defined, an EOR condition 
will be forced at the location where the record length equals the maximum 
user-specified record size. 


The character in the EOR location is checked to determine if it is a valid 
end-of-record character. Valid EOR characters are the GS character (if the SOR 
character was a GS code) and VOK or RM codes; all others are invalid. Each 
GS code is considered a valid SOR code or EOR code and will be bypassed. 


Following are the restrictions that apply when editing MDTI records: 


« All canceled records are bypassed; they are not passed to any exit routines or 
written on any data sets. The level status is set to 0. 


« All input records less than three bytes in length (SOR location, one data byte, 
and EOR location) are treated as canceled records. The remaining portion of a 
record that was longer than the user-specified maximum record size can result 
in an input record of this size. 


« Data duplication is accomplished by replacing the DUP code with the 
character from the corresponding location of the previous record. 
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« The record used for data duplication is the record returned from any user 
exits. 


¢ GS codes will not affect the level status or duplication of following records. 
e Data duplication does not occur for any of the following conditions: 
1. The DUP code is encountered in the first record of a cartridge. 


2. The DUP code is encountered in a record immediately following a canceled 
record. A canceled record is one that contains a cancel code in the SOR 
location or an input record of less than three bytes as described above. 


3. The DUP code is encountered in a position that would cause duplication of 
a position beyond the last data byte of the previous record. 


4. The DUP code is encountered in a position that would cause duplication of 
an error-replace character. 


In each case, the DUP code is replaced with the user specified error-replace 
character, and a field error is indicated. 


e Left-zero justification does not occur; the left-zero fill code (LZ) is replaced 
with the user-specified error-replace character and a field error is indicated for 
either of the following conditions: 


1. The left-zero fill code (LZ) is encountered without first having encountered 
its corresponding left-zero start code (LZS). 


2. The user-specified maximum record size is exceeded before encountering 
the valid end of a left-zero field. 


Unique codes, written by the MTST or the MTDI device, signal the program 
when all data on a cartridge has been read. For MTST cartridges, this 
end-of-cartridge code is a lowercase stop code (st) or an uppercase stop code 
(ST). For MTDI cartridges, the end-of-cartridge code is the end-data code (ED). 


IEBTCRIN terminates input from a cartridge upon encountering the 
end-of-cartridge code and rewinds the cartridge. IEBTCRIN continues to process 
cartridges until end-of-file is encountered. 


End-of-file is signaled following a rewind operation when there are no more 
cartridges in the feed hopper, the END OF FILE button is pressed, and 
end-of-cartridge for the last cartridge is recognized. An end-of-file indication will 
be passed to the OUTREC and/or ERROR exits if specified by setting register 1 
equal to 0. 


IEBTCRIN uses the following input: 


e An input data set, which contains data on tape cartridges to be read from the 
Tape Cartridge Reader (TCR). The input data set was created on either 
MTST or MTDI. 


e A control data set, which contains utility control statements that are used to 
control the functions of IEBTCRIN. 


JEBTCRIN produces the following output: 


e An output data set, which contains the sequential output produced by the 
utility as a result of processing the cartridge input according to the utility 
control statements. 


e An error output data set, which contains records that do not conform to the 
specifications for a valid record. 


e A message data set, which contains diagnostic messages. 


Control 


JEBTCRIN is controlled by job control statements and utility control statements. 
The job control statements are required to execute or invoke IEBTCRIN and to 
define the data sets that are used and produced by the program. The utility 
control statements are used to indicate the source of the input data cartridges 
(MTST or MTDI) and to specify the type of processing to be done. 


Job Control Statements 
Table 23 shows the job control statements necessary for using IEBT'CRIN. 


Table 23. IEBTCRIN Job Control Statements 


Statement Use 
JOB Initiates the job. 
EXEC Specifies the program name (PGM=IEBTCRIN) or, if the job control 


statements reside in a procedure library, the procedure name. 


SYSPRINT DD Defines a sequential message data set, which can be written to any 
QSAM-supported output device. 


SYSUT! DD _ Defines the input data set. 
SYSUT2 DD _ Defines a sequential output data set for valid records. 
SYSUT3 DD _ Defines a sequential output data set for error records. 


SYSIN DD Defines the control data set. The control data set normally resides in the input 
stream; however, it can be defined as a sequential data set or as a member of a 
partitioned data set. If this statement is not included, all utility control 
statement defaults are assumed and a message is issued to SYSPRINT. If 
DUMMY is specified, all utility control statement defaults are assumed. 


If the SYSPRINT DD statement is missing, a message is written on the operator 
console and processing continues. 


If some parameters are specified but others are omitted, IEBCTRIN attempts to 
set defaults for the missing parameters that are consistent with those supplied. 
For example, if RECFM=VBA 1s specified, IEBTCRIN assumes BLKSIZE=129 
and LRECL=125S. If LRECL, BLKSIZE, and RECFM are not specified, the 
defaults are LRECL=121, BLKSIZE=121, and RECFM=FBA. 


For the SYSUT1 DD statement, only the UNIT keyword is required. The value 
specified in UNIT=xxxx can be ‘2495’, the device address, or any other name 
that was generated in the system as a unit device name. The 
VOLUME=SER=keyword may be specified to identify the tape cartridges to be 
mounted. The volume serial number must be an externally recognizable name 
associated with the cartridges to be processed. A message is issued to the 
operator instructing that the cartridges identified by that name be mounted. If 
VOLUME is not specified, the name TCRINP is assumed and used in the mount 
message. The BUFL DCB parameter can be specified to indicate the size of 
input buffers; if BUFL is not specified, a value of 2000 is assumed. 


Fixed and variable records on the SYSUT2 or SYSUT3 data set can be blocked 
through the specification of the BLKSIZE and RECFM DCB parameters. 
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Restrictions 


SYSUT2 DD and SYSUT3 DD statements may be omitted or specified as 
DUMMY. A message is issued on SYSPRINT and processing continues. 


The DCB parameters defining the SYSIN, SYSPRINT, SYSUT2, and SYSUT3 
data sets can be supplied from any valid source (for example, DD statements or 
a data set label). Because the output (SYSUT2 and/or SYSUT3) data sets are 
not opened until the first record is ready for output (after any OUTREC and/or 
ERROR exits), DCB parameters to be supplied from an existing data set label 
are not available for records constructed before the data set is opened. 
Therefore, the DCB parameters should always be provided in the DD statement 
even though they may already exist in the label. Otherwise, defaults are used to 
construct records until the data set is opened. 


If a permanent error occurs on SYSIN, SYSUT1 (not including a data check), 
SYSUT2, or SYSUT3, a message is issued on SYSPRINT and the program is 
terminated. If a permanent input/output error occurs on SYSPRINT, both the 
failing message and a SYNADAF message indicating the error, are written on the 
programmer’s console and processing is terminated. 


¢ Because IEBTCRIN always constructs the SYSPRINT records with USASI 
(type A) control characters, type A control characters should be indicated 
when RECFM is specified. 


e If a parameter is specified on SYSPRINT DD that is not consistent with the 
other parameters, a message is issued and processing is ended. 


¢ The SYSUT1 DD statement is required for each use of IEBTCRIN. 


e The SYSUT2 DD and SYSUT3 DD statements must identify sequential data 
sets; the data sets can have fixed, variable, variable-spanned, or undefined 
records. These data sets can be written on any QSAM-supported device. 


e If editing of MTDI input is specified on the utility control statements, the 
SYSUT3 LRECL parameter should be four bytes greater than the SYSUT2 
LRECL parameter to include a four-byte Error Description Word appended to 
the front of the record by IEBTCRIN. (See “Error Records”’ earlier in this 
chapter.) For variable records on either SYSUT2 or SYSUT3, the LRECL and 
BLKSIZE DCB parameters must be large enough to include the four-byte 
record descriptor word. 


e If inconsistent parameters are specified on SYSUT2 DD or SYSUT3 DD, a 
message is issued and processing is ended. 


Utility Control Statements 


TCRGEN Statement 
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IEBTCRIN is controlled by the following utility control statements: 


e TCRGEN statement, which specifies whether MTDI or MTST input is to be 
processed and the type of processing to be performed. 


e EXITS statement, which specifies any exit routines provided by the user. 


If these statements contain errors or inconsistencies, the program is terminated 
and the appropriate diagnostics are sent to the message data set. If TCRGEN is 
not specified, standard defaults are used. 


The TCRGEN statement is used to indicate the device (MTDI or MTST) on 
which the input data was created and the type of processing to be performed on 
the input data. 


where: 
TYPE= 


specifies the device on which the magnetic tape cartridge(s) was written. 
These values can be coded: 


MTDI 
specifies that the input was created on a Magnetic Data Inscriber. 


MTST 
specifies that the input was created on a Magnetic Tape SELECTRIC 
typewriter. 


TRANS= 
specifies the type of processing to be performed on MTST input. These values 
can be coded: 


STDUC 
specifies that the MTST code is to be translated to standard EBCDIC; 
alphabetic characters are translated to uppercase. 


STDLC 
specifies that the MTST code is to be translated to standard EBCDIC; 
alphabetic characters are not translated to uppercase. 


name 
specifies a user-translate table to be used by [EBT'CRIN. The translate 
table must exist as a load module named in a user job library or the link 
library. This load module must consist of a translate table which begins at 
the entry point and conforms to the specifications for the translate 
instruction (TR) found in IBM System/370 Principles of Operation. 
Order Number GA22-7000. 


NOTRAN 
specifies that no translation and no special processing is to be performed. 
Data is passed exactly as read from the cartridge. 
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EDIT= 


specifies the type of processing to be performed on MTDI input. These values 
can be coded: 


EDITD 
specifies that the input is to be edited and that SOR and EOR codes are to } 
be deleted and not included as part of the output record. 


EDITR 
specifies that the input is to be edited and SOR and EOR codes are to be 
kept as part of the output record. 


NOEDIT 
specifies that no editing is to be performed. Data, including any group 
separator (GS) codes, is passed exactly as read from the cartridge. 


VERCHK= 


specifies whether a record-verification check is to be made on MTDI input 
that is to be edited. This parameter is valid only when TYPE=MTDI and 
either EDIT=EDITD or EDIT=EDITR are specified. These values can be 
coded: 


NOCHK 
specifies that no record-verification check is to be made. Either a record 
mark (RM) or a verify OK (VOK) code is considered a valid end-of-record 
code. 


VOKCHK 
specifies that a record-verification check is to be made. A record that does 
not contain a verify OK code is to be considered an error record. 


MINLN= 27 


specifies in bytes the length, 1, of the shortest valid, edited record. This 

parameter is valid only when TYPE=MTDI and either EDIT=EDITD or " 
EDIT=EDITR are specified. If IEBTCRIN encounters a record shorter than 2 
this specified length, the record is considered an error record. If MINLN is 

omitted, no minimum length checking is performed. 


MAXLN= n 


specifies the number of bytes, 1, plus four for the record descriptor word 
when variable records are specified, to be contained in all but the last record 
passed to the output routine when editing is not performed. IEBTCRIN does 
not indicate the end of data from one cartridge and the beginning of data 
from the next. Usually this transition from one cartridge to another occurs 
within an output record. The last record passed to the output routine contains 
only the number of bytes remaining (plus four if the record format is variable) 
and is the only record that can be shorter than the length specified by 
MAXLN. The size of the records actually written depends on the record length 
(LRECL) specified for the output data set. If MAXLN is omitted, a value of 
120 is assumed. 


REPLACE=X‘ xx’ 


specifies the hexadecimal representation of the character to be used by 
IEBTCRIN to replace error bytes. REPLACE allows the user to identify and 
possibly correct error bytes in the error exit routine or in subsequent 
processing. The specified REPLACE character should be one that does not 
normally appear in the data. X‘19’, end-of-data, is assumed if REPLACE is 
not coded. To replace error bytes on MTDI data, select a value for xx from 
Figure 35. To replace error bytes on MTST data, select a value for xx from 
Figure 36. The replacement of error bytes is accomplished before any 
specified MTST translation. 


ERROPT= 
specifies the disposition of all error records. ERROPT is ignored if a user error 
routine is specified in the EXITS statement. These values can be coded: 


NORMAL 
specifies that all error records are to be placed in the error data set 
(SYSUT3). 


NOERR 
specifies that all records (including error records) are placed in the normal 
output data set (SYSUT2). No records are placed in the error data set 
(SYSUT3). 


If STDUC, STDLC, or name is specified, certain of the MTST codes are 
processed in a special way before translation. Feed codes (FD), switch codes 
(SW), and autosearch codes (AS), both uppercase and lowercase, are deleted 
from the data. Each 61-character reference code is reduced to a single search 
code (SRC). 


A stop code, whether uppercase (ST) or lowercase (st), indicates that all data on 
a cartridge has been read. Therefore, when an MTST cartridge to be processed 
by IEBTCRIN is created, the user must not use a stop code for any purpose 
other than signaling end-of-data on the cartridge. Stop codes within meaningful 
data cause any subsequent data on the cartridge to be lost because the cartridge 
is rewound and unloaded when a stop code is encountered. 


If EDITD or EDITR is specified, the edit consists of the following functions: 


e Records are extracted one at a time from the input buffers by scanning for the 
record-delimiting codes (SOR and EOR). 


e DUP codes are replaced with the character from the corresponding location in 
the preceding record. 


¢ Left-zero fields are right aligned and leading zeros are inserted where 
necessary. 


e Left-zero start codes are deleted from the records. 


¢« Group separator codes and records that start with cancel record codes are 
bypassed. 


For MTDI input with editing specified, MAXLN is used to specify in by! s the 
length of the longest valid record after editing. If the program encounter a 
record in which a valid end-of-record cannot be determined within this :ngth, an 
end-of-record condition is forced and the record is considered an error record. 


The values that can be specified for MINLN and MAXLN are: 


¢ For MTST processing or MTDI processing without editing, MINLN is not 
specified. MAXLN should equal the number of bytes to be passed as a record. 


¢ For MTDI processing when EDIT=EDITD, MINLN should equal the number 
of bytes in the shortest valid record after editing, excluding SOR and EOR 
codes. MAXLN should equal the number of bytes in the longest valid record 
after editing, excluding SOR and EOR codes. 


« For MTDI processing when EDIT=EDITR, MINLN should equal the number 
of bytes in the shortest valid record after editing, including SOR and EOR 
codes. MAXLN should equal the number of bytes in the longest valid record 
after editing, including SOR and EOR codes. 


Note: The values for MINLN and MAXLN should not include the four-byte 
record descriptor word added to a variable-length record. 
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Table 24 shows the hexadecimal characters representing special purpose codes 
that must not be used as replacement bytes. 


Table 24. Special Purpose Codes 


MTDI Codes J 


x‘00’ (LZ) XIE’ (VOK) x‘74 (P4) 
XI (DUP) X°3C’ (RM) x5: (PS) 
x12? (LZS) poe it (PI) X‘76’ (P6) 
x‘18’ (CAN) MTZ: (P2) xT (P7) 
x‘1D’ (GS) » ey (P3) x‘78° (P8) 
MTST Codes 

x‘10’ (cr) X‘14 (CR) oF (as) 

XI (sw) XO: (SW) os (AS) 
x*13’ (fd) X*17’ (FD) x‘80’ (src) 


X‘81 through X‘FF’ 


Bit Positions O, 1 


Bit Positions 2,3 


Bit Positions 4, 5, 6, 7 
Second Hexadecimal Digit 


First Hexadecimal Digit 


Special Control: 


LZ = Left zero fill 
DUP = Duplicate 

LZS = Left zero start 
ED =End data 

GS = Group Separator 


Start of Record (SOR): 


P1 = Program level 1 
P2 = Program level 2 
P3 = Program level 3 
P4 = Program level 4 
P5 = Program level 5 
P6 = Program level 6 
P7 = Program level 7 
P8 = Program level 8 
CAN = Cancel 


End of Record (EOR): 


fet CLEC EPELELLELEL nM _ = Record mar 
VOK- = Verify OK 


This figure represents the character set and control 
codes as read from an MTDI created cartridge. 


Figure 35. MTDI Codes from TCR %, 
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The special purpose codes listed in Table 24 are used by IEBTCRIN when 
constructing records. Use of these codes causes a message to be issued and the 
utility to be terminated. 


Figure 35 shows the values that can be chosen to replace error bytes for MTDI 
input. 


Figure 36 shows the values that can be chosen to replace error bytes for MTST 
input. 


Bit Positions O,1 


a lalollafalolo[apal ala Bt Posen 2 


First Hexadecimal Digit 


Bit Positions 4,5, 6, 7 
Second Hexadecimal Digit 


cr and CR = Carrier return code 
sw and SW = Switch code 
fd and FD = Feed code 


st and ST = stop code 

tab and TAB = Tab code 

as and AS = Automatic search 
sp and SP = Space 


bsp and BSP = Backspace 
stx and STX = Stop transfer 
src and SRC = Search 


This figure represents the character set and control 
codes as read from an MTST created cartridge. 


Figure 36. MTST Codes from TCR 


Figure 37 shows MTST codes after they have been translated by IEBTCRIN 
when TRANS=STDLC is specified. 
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Bit Positions 0,1 


Bit Positions 2,3 


Bit Positions 4, 5, 6, 7 
Second Hexadecimal Digit 


First Hexadecimal Digit 


TAB = Tab code 
CR = Carrier return 
BSP = Backspace 


SRC = Search 
pepe CEELPELELELLLE STX = Stop tense 
SP = Space 


Note: The STDUC option permits translating 
both lowercase and uppercase alphabetic 
characters to uppercase. 


Figure 37. MTST Codes after Translation by IEBTCRIN with TRANS = STDCL 


EXITS Statement 


The EXITS statement is used to identify user-supplied exit routines, which must 
exist in either the user job library or the link library. 


Upon entry, a parameter list is supplied to the exit routine. Upon returning from 
the exit routine, the user must provide an acceptable return code. See ‘‘Appendix 
A: Exit Routine Linkage.” 
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The format of the EXITS statement is: 


where: 


ERROR= routinename 
specifies the symbolic name of a routine that receives control before an error 
record is passed to the error output data set (SYSUT3). This exit routine can 


be used to analyze and, if possible, correct the error record. This parameter 
nullifies any ERROPT value. 


OUTREC= routinename 
specifies the symbolic name of a routine that receives control before the 
record is passed to the normal output data set (SYSUTZ2). In this exit routine, 
the user can process the record and perform his own output if output other 
than the SYSUT2 data set is desired. Any modification of an edited MTDI 
record may affect the editing of following records because the record returned 
from this exit is used to accomplish data duplication in the record that follows. 
If the SYSUT2 data set has specified variable length records, a four-byte 
RDW is appended to the front of the record. 


OUTHDR2= routinename 
specifies the symbolic name of a routine that receives control during the 
opening of the SYSUT2 data set; this exit routine can be used to create user 
output header labels for the normal output data set (SYSUT2). 


OUTHDR3= routinename 
specifies the symbolic name of a routine that receives control during the 
opening of the SYSUT3 data set; this exit routine can be used to create user 
output header labels for the error data set (SYSUT3). 


OUTTLR2= routinename 
specifies the symbolic name of a routine that receives control during the 
closing of the SYSUT2 data set; this exit routine can be used to create user 
output trailer labels for the normal output data set (SYSUT2). 


OUTTLR3= routinename 
specifies the symbolic name of a routine that receives control during the 
closing of the SYSUT3 data set; this exit routine can be used to create user 
output trailer labels for the error data set (SYSUT3). 


If MTDI is edited, a four-byte (EDW) is appended to the front of each error 
record describing the error condition. For further definition of the EDW, see 
‘Error Records” earlier in this chapter. If the SYSUT3 DD statement specified 
variable-length records, a four-byte Record Descriptor Word (RDW) is also 
appended to the front of the record. For further description of the RDW, see 
OS/VS Supervisor Services and Macros, Order Number GC27-6979. 


The user-supplied routines specified in ERROR and OUTREC can be used to 
examine and modify any byte in the record or EDW. The record length can be 
changed, subject to the following restrictions: 


¢ A work area used to construct the records is allocated by the program equal in 
size to the largest of (1) MAXLN, (2) LRECL on SYSUT2, or (3) LRECL 
on SYSUT3. 
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e The record length must not be increased beyond this size. Overlaying of other 
work areas may then occur, causing unpredictable results. 


The new record length must be placed in the location pointed to by the second 
parameter word as received at entry to the routine. This length must include the 
EDW and RDW (if applicable). It is not necessary to modify the RDW because 
it is re-created if the record is to be written by IEBTCRIN. However, if the user 
does his own output from this routine, he must ensure that the RDW is correct 
for the record. 


If IEBTCRIN is to write the record, the length of the output record depends on 
the RECFM specification, as follows: 


e Fixed and variable records may have a maximum length equal to LRECL. 
Records larger than this are truncated. 


e Undefined records may have a maximum length equal to BLKSIZE. Records 
larger than this are truncated. 


These record lengths include the EDW and RDW, where applicable. 


The record length returned from the error exit is used to establish the location of 
the last data byte in the record. The location is used to control data duplication 
in the following record. However, it is not used for checking the record length of 
subsequent records. 


Modifications to the EDW, record, or record length may affect the editing of 
subsequent records. If the input is not edited, the user can examine and modify 
any byte in the record. The record length can also be changed, subject to the 
MTDI-editing restrictions. 


Return Codes from IEBTCRIN 


IEBTCRIN Examples 
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At job termination, IEBTCRIN produces a return code to indicate the results of 
program execution. Table 25 shows the return codes used by IEBTCRIN. 


Table 25. IEBTCRIN Return Codes 

Return 

Code Interpretation 

00 Normal termination. 

04 Warning message issued; execution permitted. Conditions leading to issuance of this 


code are: (1) SYSPRINT, SYSIN, SYSUT2, or SYSUT3 DD statements missing and 
(2) DCB parameters missing in SYSUT2 or SYSUT3 DD statements. 


12 Diagnostic error message issued; execution terminated. Conditions leading to 
issuance of this code are: (1) SYSUT1 DD statement missing, (2) conflicting DCB 
parameters in DD statements, and (3) invalid or conflicting utility control 
statements. 


16 Terminal error message issued; execution terminated. Conditions leading to 
issuance of this code are: (1) permanent input/output errors (not including data 
checks on the TCR), (2) unsuccessful opening of data sets, (3) requests for 
termination by user exit routine, (4) insufficient storage available for execution, and 
(5S) user exit routine not found. 


The following examples illustrate some of the uses of IEBTCRIN. Table 26 can 
be used as a quick reference guide to IEBTCRIN examples. The numbers in the 
‘“Example’’ column point to examples that follow. 


IEBTCRIN Example 1 


IEBTCRIN Example 2 


Table 26. IEBTCRIN Example Directory 


Data Set 
Operation Organization Device Comments Examp 
Edit MDTI input Sequential 2314 Disk, Fixed-blocked output. Error 
9-track tape exit routine specified | 
Invoke JIEBTCRIN 
with LINK macro 
instruction 2 


In this example, input from a tape cartridge is to be edited with normal records 
written to a 2314 volume and error records written to a 9-track tape volume. 


The example follows: 


//JOBNAME JOB 0,SMITH,MSGLEVEL=1 

//STPNAME EXEC PGM=IEBTCRIN 

//SYSPRINE DD SYSOUT=A 

J / SLSUT | DD UNIT=TCR, VOLUME=SER=MYTAPE, DCB=( BUFL=3000 ) 
ff SYSUTZ DD DSNAME=GOODSET, DISP=( NEW, CATLG ), UNIT=2314, 


// VOLUME=SER=111222,SPACE=(TRK,(10,10)), 

// DCB=( LRECL=100, BLKSIZE=1000, RECFM=EB ) 

//SYSUT3 = DD DSNAME=ERRSET, UNIT=2400, 

// VOLUME=SER=000001,DISP=(NEW,KEEP ), 

// DCB=( BLKSIZE=104,RECFM=U ) 

//SYSIN DD * 
TCRGEN TYPE=MTDI , EDIT=EDITD, MAXLN=100,REPLACE=X'5B'! 
EXITS ERROR=MYERR 

/* 


The control statements are discussed below: 


¢ SYSUT1 DD defines the input tape cartridge data set. A console message 
instructs the operator to mount a set of cartridges named MYTAPE. The two 
input buffers are each 3000 bytes long (BUFL). The UNIT parameter assumes 
that TCR has been system generated as a unit name for the Tape Cartridge 
Reader. 


¢ SYSUT2 DD defines a sequential data set for the normal output records. The 
data will be written to a 2314 volume. 


« SYSUT3 DD defines a sequential data set for the error records. The records 
are undefined. with a maximum block size of 104 bytes, including a 4-byte 
error description word. 


¢ SYSIN DD defines the control data set, which follows in the input stream. 


¢ TCRGEN indicates MTDI input. The input is to be edited with SOR and 
EOR codes deleted, the maximum valid record length is to be 100 bytes, and 
the replace character is a hexadecimal “5B”. VERCHK is defaulted to 
NOCHK. Minimum record-length checking is not requested. 


¢ EXITS indicates that a user has provided an exit routine to handle error 
records. Because no job library has been specified, the exit routine (MYERR) 
must reside in the link library. 


In this example, IEBTCRIN is invoked via the LINK macro instruction in an 
Assembler language program. An alternate name has been assigned to each of 
the DD statements used by IEBTCRIN. The job control for this step must 
include DD statements with the alternate DD names. 
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The example follows: 


LINK EP=IEBTCRIN, PARAM=(OPTLIST,DDNAME ), VL=1 
CNOP 2,4 (OPTLIST must be on halfword boundary) 
OPTEIST DC H'O' (Length must be zero for IEBTCRIN) 
CNOP 2,4 (DDNAME list must be on halfword boundary) 
DDNAME DC H'82' (Length of DDNAME list) 


DE Br td: 

DC C'NEWIN ' (Alternate DDNAME for SYSIN) 

Bie C'NEWPRINT' (Alternate DDNAME for SYSPRINT) 
DG sia Oh 

DC C'NEWUT1 ' (Alternate DDNAME for SYSUT 1) 
DC C'NEWUT2 ' (Alternate DDNAME for SYSUT2) 
es C'NEWUT3 ' (Alternate DDNAME for SYSUT3) 
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IEBUPDTE Program 


IEBUPDTE is a data set utility used to incorporate IBM and user-generated 
source language modifications into sequential or partitioned data sets. (See 
“Introduction” for general data set utility information.) Exits are provided for 
user routines that process user header and trailer labels. 


IEBUPDTE can be used to: 
e Create and update symbolic libraries. 
e Incorporate changes to partitioned members or sequential data sets. 


e Change the organization of a data set from sequential to partitioned or vice 
versa. 


At the completion or termination of IEBUPDTE, the highest return code 
encountered within the program is passed to the calling program. 


Creating and Updating Symbolic Libraries 


Incorporating Changes 


IEBUPDTE can be used to create a library of partitioned members consisting of 
(at the most) 80-byte logical records. In addition, members can be added directly 
to an existing library, provided that the original space allocations are sufficient to 
incorporate the new members. In this manner, a cataloged procedure can be 
placed in a procedure library, or a set of job or utility control statements can be 
placed as a member in a partitioned library. 


IEBUPDTE can be used to modify an existing partitioned or sequential data set. 
Logical records can be replaced, deleted, renumbered, or added to the member or 
data set. 


A sequential data set residing on a tape volume can be used to create a new 
master (that is, a modified copy) of the data set. A sequential data set residing 
on a direct access device can be modified either by creating a new master or by 
modifying the data set directly on the volume on which it resides. 


A partitioned data set can be modified either by creating a new master or by 
modifying the data set directly on the volume on which it resides. 


Changing Data Set Organization 


Input and Output 


IEBUPDTE can be used to change the organization of a data set from sequential 
to partitioned, or to change a member of a partitioned data set to a sequential 
data set (the original data set, however, remains unchanged). In addition, logical 
records can be replaced, deleted, renumbered, or added to the member or data 
set. 


IEBUPDTE uses the following input: 


« An input data set (also called the old master data set), which is to be modified 
or used as source data for a new master. The input data set is either a 
sequential data set or a member of a partitioned data set. 


¢ A control data set, which contains utility control statements and, if applicable, 
input data. The data set is required for each use of IEBUPDTE. 
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Control 


Job Control Statements 
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IEBUPDTE produces the following output: 


e An output data set, which is the result of the IEBUPDTE operation. The data 
set can be either sequential or partitioned. It can be either a new data set 
(that is, created during the present job step) or an existing data set, modified 
during the present job step. 


e A message data set, which contains the utility program identification, control 
statements used in the job step, modification made to the input data set, and 
diagnostic messages, if applicable. The message data set is sequential. 


IEBUPDTE provides a return code to indicate the results of program execution. 
The return codes and their meanings are: 


e OQ, which indicates successful completion. 


e 04, which indicates that a control statement is coded incorrectly or used 
erroneously. If either the input or output is sequential, the job step is 
terminated. If both are partitioned, the program continues processing with the 
next function to be performed. 


e 12, which indicates an unrecoverable error. The job step is terminated. 


¢ 16, which indicates that a label-processing code of 16 was received from a 
user’s label-processing routine. The job step is terminated. 


IEBUPDTE is controlled by job control statements and utility control statements. 


The job control statements are required to execute or invoke IEBUPDTE and to 
define the data sets that are used and produced by the program. The utility 
contro] statements are used to control the functions of IEBUPDTE and, in 
certain cases, to supply new or replacement data. 


Table 27 shows the job control statements necessary for using IEBUPDTE. 


Table 27. IEBUPDTE Job Control Statements 


Statement Use 
JOB Initiates the job. 
EXEC Specifies the program name (PGM=IEBUPDTE), or, if the job control 


Statementsreside in a procedure library, the procedure name. Additional 
information can be specified in the PARM parameter of the EXEC statement; 
see “PARM Information on the EXEC Statement” below. 


SYSPRINT DD Defines a sequential message data set. The data set can be written to a system 
output device, a tape volume, or a direct access volume. 


SYSUT!1 DD _ Defines the input (old master) data set. It can define a sequential data set on a 
card reader, a tape volume, or a direct access volume. Or, it can define a 
partitioned data set on a direct access volume. This DD statement is not 
required if the input consists solely of the control data set. 


SYSUT2 DD Defines the output data set. It can define a sequential data set on a card 
punch, a printer, a tape volume, or a direct access device. It can define a 
partitioned data set on a direct access device. 


SYSIN DD Defines the control data set. The control data set normally resides in the input 
stream; however, it can be defined as a member of a partitioned data set. 


The input and output data sets contain blocked or unblocked logical records with 
record lengths of up to 80 bytes. The input and output data sets may have 
different block sizes as long as they are multiples of the logical record length. 


If an ADD operation is specified with PARM=NEW on the EXEC card, the 
SYSUT1 DD statement need not be coded. See ‘““PARM Information on the 


EXEC Statement”’ below. Refer to ‘‘Function Statement’’ below for a discussion 
of the ADD operation. 


“ 


Restrictions 


If an UPDATE operation is specified, the SYSUT2 DD statement should not be 
coded. Refer to ‘“‘Function Statement”’ for a discussion of the UPDATE 
operation. 


If the SYSUT1 DD statement defines a sequential data set, the file sequence 
number of that data set must be included in the LABEL keyword (unless the 
data set is the first or only data set on the volume). 


If both the SYSUT1 and SYSUT2 DD statements specify standard user labels 
(SUL), IEBUPDTE copies user labels from SYSUT1 to SYSUT2. See “Appendix 
E: Processing User Labels” for a discussion of the available options for user label 
processing. 


If the SYSUT1 and SYSUT2 DD statements define the same partitioned data set, 
the old master data set can be updated without creating a new master data set; in 
this case, a copy of the updated member or members is written within the extent 
of the space originally allocated to the old master data set. Subsequent referrals 
to the updated member(s) will point to the newly written member(s). The 
member names themselves should not appear on the DD statements; they should 
be referenced only through IEBUPDTE control statements. 


¢ The SYSPRINT DD statement is required for each use of IEBUPDTE. 


¢« The output data set can have a blocking factor that is different from the input 
data set; however, if insufficient space is allocated for reblocked records, the 
update request is terminated. 


¢ When adding a member to an existing partitioned data set using an ADD 
Function statement, any DCB parameters specified on the SYSUT1 and 
SYSUT2 DD statements (or the SYSUT2 DD statement if that is the only one 
specified) must be the same as the DCB parameters already existing for the 
data set. 


¢ Space must be allocated for an output data set (SYSUT2 DD statement) that 
is to reside on a direct access device, unless the data set is an existing data set, 
in which case space should not be allocated. 


« The SYSUT2 DD statement must not specify a DUMMY data set. 


e If the SYSUTI and SYSUT2 DD statements define the same sequential data 
set (direct access only), only those operations that add data to the end of the 
existing data set can be made. In these cases: 


1. The PARM parameter of the EXEC statement must imply or specify MOD. 
(See ‘““PARM Information on the EXEC Statement”’ below.) 


2. The DISP parameter of the SYSUT1 DD statement must specify OLD. 
3. The DISP parameter of the SYSUT2 DD statement must specify MOD. 
e The SYSIN DD statement is required for each use of IEBUPDTE. 


e The message data set has a logical record length of 121 bytes, and consists of 
fixed-length, blocked or unblocked records with an ASA control character in 
the first byte of each record. The input and output data sets have a logical 
record length of 80 bytes or less, and consist of standard fixed-blocked 
(RECFM=FB) or unblocked records. The control data set contains 80-byte, 
blocked or unblocked records. 
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PARM Information on the EXEC Statement 


Additional information can be coded in the PARM parameter of the EXEC 


statement, as follows: 
PARM=({ NEW}, |[inhdr] ,[intlr] ) 
{MOD} 


Following are the PARM values: 


¢ NEW, which specifies that the input consists solely of the control data set. 
The input data set is not defined if NEW is specified. 


¢ MOD, which specifies that the input consists of both the contro] data set and 
the input data set. If neither NEW nor MOD is coded, MOD is assumed. 


e “inhdr,’’ which specifies the symbolic name of a routine that processes the 
userheader label on the volume containing the control data set. 


e “intlr,” which specifies the symbolic name of a routine that processes the user 
trailer label on the volume containing the control data set. 


For a detailed discussion of the processing of user labels as data set descriptors, 
refer to “Appendix E: Processing User Labels.” 


Utility Control Statements 


Function Statement 
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The utility control statements used to control IEBUPDTE are: 
e Function statement, which is used to initiate an IEBUPDTE operation. 


¢ Detail statement, which is used with the Function statement for special 
applications. 


e Data statement, which is a logical record of data to be used as a new or 
replacement record in the output data set 


e LABEL statement, which is used to indicate that the following data statements 
are to be treated as user labels. 


e ALIAS statement, which is used to assign aliases. 


e ENDUP statement, which is used to terminate IEBUPDTE. 


The Function statement is used to initiate an IEBUPDTE operation. At least one 
Function statement must be provided for each member or data set to be 
processed. 


A member or a data set can be added directly to an old master data set if the 
space originally allocated to the old master is sufficient to incorporate that new 
member or data set. 


When a member replaces an identically named member on the old master data 
set or a member is changed and rewritten on the old master, the alias (if any) of 
the original member still refers to the original member. However, if an identical 
alias is specified for the newly written member, the original alias entry in the 
directory is changed to refer to the newly written member. 


J 


The format of the Function statement is: 


wnere: 


./ 


is required and must appear in columns 1 and 2. 


name 
specifies an optional name which begins in column 3 and extends no further 
than column 10. 


ADD 
specifies that a member or a data set is to be added to an old master data set. 
If a member is to be added and the member name already exists in the old 
master data set, processing is terminated. If, however, PARM=NEW is 
specified on the EXEC statement, the member is replaced. For a sequential 
output master data set, PARM=NEW must always be specified on the EXEC 
statement. At least one blank must precede and follow ADD. 


REPL 
specifies that a member of a data set is being entered in its entirety as a 
replacement for a sequential data set or for a member of the old master data 
set. The member name must already exist in the old master data set. At least 
one blank must precede and follow REPL. 


CHANGE 
specifies that modifications are to be made to an existing member or data set. 
Use of the CHANGE Function statement without a NUMBER or DELETE 
Detail statement, or a Data statement causes an error condition. At least one 
blank must precede and follow CHANGE. 


REPRO 
specifies that a member or a data set is to be copied in its entirety to a new 
master data set. At least one blank must precede and follow REPRO. 


LIST=ALL 
specifies that the SYSPRINT data set is to contain the entire updated member 
or data set and the control statements used in its creation. If LIST is omitted, 
the SYSPRINT data set contains modifications and control statements only. If 
UPDATE was specified, the entire updated member is listed only when 
renumbering has been done. 
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SEQFLD= dd! 
specifies, in decimal, the starting column (up to column 80) and length (8 or 
less) of sequence numbers within existing logical records and subsequent Data 
statements. Note that the starting column specification (dd) plus the length : 
(/) cannot exceed the logical record length (LRECL) plus 1. If SEQFLD is 2 
omitted, 738 is assumed, that is, an eight-byte sequence number beginning in 
column 73. Therefore, if existing logical records and subsequent Data 
statements have sequence numbers in columns 73 through 80, this keyword 
need not be coded. In any case, sequence numbers on incoming Data 
statements and existing logical records must be padded to the left with enough 
zeros to fill the length of the sequence field. 


NEW= 
specifies the organization of the old master data set and the organization of 
the updated output. NEW should not be specified unless the organization of 
the new master data set is different from the organization of the old master. 
Refer to Table 28 for the use of NEW with NAME and MEMBER. These 
values can be coded: 


PO 
specifies that the old master data set is a sequential data set, and that the 
updated output is to become a member of a partitioned data set. 


PS 
specifies that the old master data set is a partitioned data set, and that a 
member of that data set is to be converted into a sequential data set. 


MEMBERS cccccccc 

specifies a name to be assigned to the member placed in the partitioned data 

set defined by the SYSUT2 DD statement. MEMBER is used only when 

SYSUT1 defines a sequential data set, SYSUT2 defines a partitioned data set, 

and NEW=PO is specified. Refer to Table 28 for the use of MEMBER with 2 
NEW. 


COLUMN2 dd 
specifies, in decimal, the starting column of a data field within a logical record 
image. The field extends to the end of the image. Within an existing logical 
record, the data in the defined field is replaced by data from a subsequent 
Data statement. COLUMN is valid only when CHANGE is coded. 


UPDATE=INPLACE 
specifies that the old master data set is to be updated within the space it 
actually occupies. The old master data set must reside on a direct access 
device. UPDATE is valid only when coded with CHANGE. 


INHDR= cccccccc 
specifies the symbolic name of the user routine that handles any user input 
(SYSUT1) header labels. When used with UPDATE, this routine assumes a 
special function. This parameter is valid only when a sequential data set is 
being processed. See ‘““LABEL Statement”’ for a discussion of this function. 


INTLR= cccccccc 
specifies the symbolic name of the user routine that handles any user input 
(SYSUT1) trailer labels. INTLR is valid only when a sequential data set is 
being processed, but not when UPDATE is coded. 


“ty 


OUTHDR= cccccccc 
specifies the symbolic name of the user routine that handles any user output 


(SYSUT2) header labels. OUTHDR is valid only when a sequential data set is 
being processed, but not when UPDATE is coded. 


OUTTLRE= cccccccc 
specifies the symbolic name of the user routine that handles any user output 
(SYSUT2) trailer labels. OUTTLR is valid only when a sequential data set is 
being processed, but not when UPDATE is coded. 


TOTAL= 
specifies that exits to a user’s routine are to be provided prior to writing each 
record. This parameter is valid only when a sequential data set is being 
processed. These values are coded: 


routinename 
specifies the name of the user’s totaling routine. 


size 
specifies the number of bytes required for the user’s data. The size should 
not exceed 32K, nor be less than 2 bytes. In addition, the keyword 
OPTCD=T must be specified for the SYSUT2 (output) DD statement. 
Refer to “Appendix A: Exit Routine Linkage” for a discussion of linkage 
conventions for user routines. 


NAME= cccccccc 
indicates the name of the member placed into the partitioned data set. The 
member name need not be specified in the DD statement itself. NAME must 
be provided to identify each input member. Refer to Table 28 for the use of 
NAME with NEW. This parameter is valid only when a member of a 
partitioned data set is being processed. 


LEVEL= hh 
specifies the change (update) level in hexadecimal (OO-FF). The level number 
is recorded in the directory entry of the output member. This parameter is 
valid only when a member of a partitioned data set is being processed. 


SOURCE= x 
specifies user modifications when the x value is 0, or IBM modifications 
whenthe x value is 1. The source is recorded in the directory entry of the 
output member. This parameter is valid only when a member of a partitioned 
data set is being processed. 


SSI= hhhhhhhh 
specifies eight hexadecimal characters of system status information (SSI) to be 
placed in the directory of the new master data set as four packed hexadecimal 
bytes of user data. This parameter is valid only when a member of a 
partitioned data set is being processed. SSI overrides any LEVEL or SOURCE 
data given on the same Function statement. 


Members can be deleted from a copy of a library by being omitted from a series 
of REPRO Function statements within the same job step. 


One sequential data set can be copied in a given job step. A sequential data set 
is deleted by being omitted from a series of job steps which copy only the 
desired data sets to a new volume. If the NEW subparameter is coded in the 
EXEC statement, only the ADD Function statement is permitted. 


Figure 38 shows how the system status information (SSI=0A3C123B) is packed. 
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Change level Flag byte Serial number 


byte 1 byte 2 byte 3 


Figure 38. Format of System-Status Information 

When UPDATE is specified: 

e The SYSUT2 DD statement is not coded. 

e The PARM parameter of the EXEC statement must imply or specify MOD. 
e The NUMBER statement can be used to specify a renumbering operation. 

¢« Data statements can be used to specify replacement information only. 


e One CHANGE Function statement and one UPDATE parameter are permitted 
per job step. 


e No functions other than replacement, renumbering, and header label 
modification (via the LABEL statement) can be specified. 


e Only replaced records are listed unless the entire data set is renumbered. 
e System status information cannot be changed. 


Within an existing logical record, the data in the field defined by COLUMN is 
replaced by data from a subsequent data statement, as follows: 


1. IEBUPDTE matches a sequence number of a Data statement with a sequence 
number of an existing logical record. In this manner, the COLUMN 
specification is applied to a specific logical record. 


2. The information in the field within the Data statement replaces the 
information in the field within the existing logical record. For example, J 
COLUMN=40 indicates that columns 40 through 80 (assuming 80-byte 
logical records) of a subsequent Data statement are to be used as replacement 
data for columns 40 through 80 of a logical record identified by a matching 
Sequence number. (A sequence number in an existing logical record or Data 
statement need not be within the defined field.) 


The COLUMN specification applies to the entire function, with the exception of: 
¢ Logical records deleted by a subsequent DELETE Detail statement. 


e Subsequent Data statements not having a matching sequence number for an 
existing logical record. 


e Data statements containing information to be inserted in the place of a deleted 
logical record or records. 


Table 28 shows the use of NEW, MEMBER, and NAME parameters for 
different input and output data set organizations. 
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Table 28. NEW, MEMBER, and NAME Parameters 


Input Data Set Output Data Set Parameter 
Organization Organization Combinations 


Partitioned Partitioned With an ADD Function statement, use NAME to specify 
the name of the member to be placed in the partitioned 
data set defined by the SYSUT2 DD statement. If an 
additional name is required, an ALIAS statement can 
also be used. 


With a CHANGE, REPL, or REPRO Function 
statement,use NAME to specify the name of the member 
within the partitioned data set defined by the SYSUTI 
DD statement. If a different or additional name ts 
desired for the member in the partitioned data set 
defined by the SYSUT2 DD statement, use an ALIAS 
statement also. 


None Partitioned (New) With each ADD Function statement, use NAME to 
assigna name for each member to be placed in the 
partitioned data set. 


Partitioned Sequential With a Function statement, use NAME to specify the 
name of the member in the partitioned data set defined 
by the SYSUT1 DD statement. Use NEW=PS to specify 
the change in organization from partitioned to 
sequential. (The name and file sequence number 
assigned to the output master data set are specified in 
the SYSUT2 DD statement.) 


Sequential Partitioned With a Function statement, use MEMBER to assign a 
name to the member to be placed in the partitioned data 
set defined by the SYSUT2 DD statement. Use 
NEW=PO to specify the change in organization from 
sequential to partitioned. 


For a detailed discussion of the processing of user labels as data set descriptors, 
and for a discussion of user-label totaling, see ““Appendix E: Processing User 
Labels.” 


A Detail statement is used with a Function statement for certain applications, 
such as deleting or renumbering selected logical records. 


Note: Logical records cannot be deleted in part; that is, a COLUMN 
specification in a Function statement is not applicable to records that are to be 
deleted. Each specific sequence number is handled only once in any single 
operation. 

The format of a Detail statement is: 


ar “ 


7 77) 
4 


at 


> 
ee re. 


-/ 


is required and must appear in columns 1 and 2. 


name 
specifies an optional name which begins in column 3 and extends no further 
than column 10. 
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NUMBER 
specifies, when coded with a CHANGE Function statement, that the sequence 
number of one or more logical records is to be changed. It specifies, when 
coded with an ADD or REPL Function statement, the sequence numbers to be 
assigned to the records within new or replacement members or data sets. 
When used with an ADD or REPL Function statement, no more than one J 
NUMBER Detail statement is permitted for each ADD or REPL Function 
statement. If NUMBER is coded, it must be preceded and followed by at least 
one blank. 


DELETE 
specifies, when coded with a CHANGE Function statement, that one or more 
logical records are to be deleted from a member or data set. If DELETE is 
coded, it must be preceded and followed by at least one blank. 


SEQI= 
specifies records to be renumbered, deleted, or assigned sequence numbers. 
These values can be coded: 


CECCCECE 
specifies the sequence number of the first logical record to be renumbered 
or deleted. This value is not coded in a NUMBER Detail statement that is 
used with an ADD or REPL Function statement. When this value is used 
in an insert operation, it specifies the existing logical record after which an 
insert is to be made. It must not equal the number of a statement just 
replaced or added. Refer to the INSERT parameter for additional 
discussion. 


ALL 
specifies a renumbering operation for the entire member or data set. ALL is 
used only when a CHANGE Function statement and a NUMBER Detail 
statement are used. ALL must be coded if sequence numbers are to be | 
assigned to existing logical records having blank sequence numbers. If ALL - 
is not coded, all existing logical records having blank sequence numbers are 
copied directly to the output master data set. When ALL is coded: (1) 
SEQ2 need not be coded and (2) one NUMBER Detail statement is 
permitted per Function statement. Refer to the INSERT parameter for 
additonal discussion. 


SEQ2= cccccccc 
specifies the sequence number of the last logical record to be renumbered or 
deleted. If only one record is to be deleted, the SEQ! and SEQ2 
specifications must be identical. SEQ2 is not coded in a NUMBER Detail 
statement that is used with an ADD or REPL Function statement. 


NEW1= cccccccc 
specifies the first sequence number assigned to new or replacement data, or 
specifies the first sequence number assigned in a renumbering operation. A 
value specified in NEW1 must be greater than a value specified in SEQI 
(unless SEQI=ALL is specified, in which case this rule does not apply). This 
parameter is valid only in a NUMBER Detail statement. 


INCR= cccccccc 
specifies an increment value used for assigning successive sequence numbers to 
new or replacement logical records, or specifies an increment value used for 
renumbering existing logical records. This parameter is valid only in a 
NUMBER Detail statement. 
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INSERT=YES 
specifies the insertion of a block of logical records. The records, which are 
Data statements containing blank sequence numbers, are numbered and 
inserted in the output master data set. INSERT is valid only when coded with 
both a CHANGE Function statement and a NUMBER Detail statement. 


When INSERT is coded: 


e The SEQI parameter specifies the existing logical record after which the 
insertion is to be made. The SEQ2 parameter need not be coded; SEQI=ALL 
cannot be coded. 


e The NEWI parameter assigns a sequence number to the first logical record to 
be inserted. 


member or data set from the point of the first insertion; the member or data 
set is renumbered until an existing logical record is found whose sequence 
number is equal to or greater than the next sequence number to be assigned. 
If no such logical record is found, the entire member or data set is 
renumbered. 


¢« Additional NUMBER Detail statements, if any, must specify INSERT. If a 
prior numbering operation renumbers the logical record specified in the SEQ] 
parameter of a subsequent NUMBER Detail statement, any NEWI or INCR 
parameter specifications in the latter NUMBER statement are overridden. The 
prior increment value is used to assign the next successive sequence numbers. 
If a prior numbering operation does not renumber the logical record specified 
in the SEQI parameter of a subsequent NUMBER Detail statement, the latter 
Statement must contain NEWI and INCR specifications. 


e The INCR parameter is used to renumber as much as is necessary of the ea 


e The block of Data statements to be inserted must contain blank sequence 
numbers. 


e The insert operation is terminated when a Function statement, a Detail 
Statement, an end-of-file indication, or a Data statement containing a sequence 
number is encountered. 


The SEQ1, SEQ2, NEWI1, and INCR parameters (with the exception of 
SEQ=ALL) specify eight-character (maximum) decimal numbers. Only the 
significant numbers of a value need be coded; for example, SEQ! =00000010 
can be shortened to SEQ1=10. 


Data Statement 


A Data Statement is used with a Function statement, or with a Function statement 
and a Detail statement. It contains a logical record used as replacement data for 
an existing logical record, or new data to be incorporated in the output master 
data set. 


Each Data statement contains one logical record, which begins in the first column 
of the Data statement. The length of the logical record is equal to the logical 
record length (LRECL) specified for the output master data set. Each logical 
record contains a sequence number to determine where the data is to be placed 
in the output master data set. 


When used with a CHANGE Function statement, a Data statement contains new 
or replacement data, as follows: 


e If the sequence number in the Data statement is identical with a sequence 
number in an existing logical record, the Data statement replaces the existing 
logical record in the output master data set. 
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¢ If no corresponding sequence number is found within the existing records, the 
Data statement is inserted in the proper collating sequence within the output 
master data set. (For proper execution of this function, all records in the old 
master data set must have a sequence number.) 


« If a Data statement with a sequence number is used and INSERT=YES was 
specified, the insert operation is terminated. IEBUPDTE will continue 
processing if this sequence number is at least equal to the next old master 
record (record following the referred to sequence record). 


When used with an ADD or REPL Function statement, a Data statement 
contains new data to be placed in the output master data set. 


Sequence numbers within the old master data set are assumed to be in ascending 
order. 


Sequence numbers in Data statements must be in the same relative position as 
sequence numbers in existing logical records. (Sequence numbers are assumed to 
be in columns 73 through 80; if the numbers are in columns other than these, the 
length and relative position must be specified in a SEQFLD parameter within a 
preceding Function statement. ) 


The LABEL statement indicates that the following data statements are to be 
treated as user labels. These new user labels are placed on the output data set. 
The next Function statement indicates to IEBUPDTE that the last label data 
statement of the group has been read. 


There can be no more than two LABEL statements per execution of 
IEBUPDTE. There can be no more than eight label data statements following 
any LABEL statement. The first four bytes of each 80-byte label data statement 
must contain ““UHLn” or “UTLn’’, where nv is 1 through 8, for input header or 
input trailer labels respectively, to conform to IBM standards for user labels. 
Otherwise, data management will overlay the data with the proper four 
characters. 


When IEBUPDTE encounters a LABEL statement, it reads up to eight Data 
statements and saves them for processing by user output label routines. If there 
are no such routines, the saved records are written by OPEN or CLOSE as user 
labels on the output data set. If there are user output label processing routines, 
IEBUPDTE passes a parameter list to the output label routines. This parameter 
list is described fully in ““Appendix A: Exit Routine Linkage.’ The label buffer 
contains a label data record which the user routine can process before the record 
is written as a label. If the user routine specifies (via return codes to 
IEBUPDTE) more entries than there are label data records, the label buffer will 
contain meaningless information for the remaining entries to the user routine. 


The position of the LABEL statement in the SYSIN data set, relative to 
Function statements, indicates the type of user label that follows the LABEL 
Statement: 


¢ To create output header labels, place the LABEL statement and its associated 
label data statements before any Function statements in the input stream. A 
Function statement, other than LABEL, must follow the last label data 
statement of the group. 


ALIAS Statement 


e To create output trailer labels, place the LABEL statement and its associated 
label data statements after any Function statements in the input stream, but 
before the ENDUP statement. The ENDUP statement is not optional in this 
case. It must follow the last label data statement of the group if IEBUPDTE is 
to create output trailer labels. 


When UPDATE is specified in a Function statement, user input header labels can 

be updated by user routines, but input trailer and output labels cannot be 

updated by user routines. User labels cannot be added or deleted. User input 

header labels are made available to user routines by the label buffer address in 

the parameter list. See ‘Appendix E: Processing User Labels” for a complete 

discussion of the linkage between utility programs and user-label processing 
routines. The return codes when UPDATE is used differ slightly from the standard 
codes discussed in ‘“‘Appendix E: Processing User Labels,” as follows: ak 


e 0, which specifies that the system resumes normal processing; any additional 
user labels are ignored. 


e 4, which specifies that the system does not write the label. The next user label 
is read into the label buffer area and control is returned to the user’s routine. 
If there are no more user labels, the system resumes normal processing. 


e 8, which specifies that the system writes the user labels from the label buffer 
area and resumes normal processing. 


e 12, which specifies that the system writes the user label from the label buffer 
area, then reads the next input label into the label buffer area and returns 
control to the label processing routine. If there are no more user labels, the 
system resumes normal processing. 


If the user wants to examine the replaced labels from the old master data set, he 
must: 


1. Specify an update of the old master by coding the UPDATE parameter in a 
Function statement. 


2. Include a LABEL statement in the input data set for either header or trailer 
labels. 


3. Specify a corresponding user label routine. 


If the above conditions are met, fourth and fifth parameter words will be added 
to the standard parameter list. The fourth parameter word is not now used; the 
fifth contains a pointer to the replaced label from the old master. In this case, 
the number of labels supplied in the SYSIN data set must not exceed the number 
of labels on the old master data set. If the user specifies, via return codes, more 
entries to the user’s header label routine than there are labels in the input stream, 
the first parameter will point to the current header label on the old master data 
set for the remaining entries. In this case, the fifth parameter is meaningless. 


The ALIAS statement is used to create or retain an alias in an output 
(partitioned) master directory. The ALIAS statement can be used with any of the 
Function statements. Multiple aliases can be assigned to each member. 
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The format of the ALIAS statement is: 


Rey at ss eT 


where: 


f 


is required and must appear in columns 1 and 2. 


name 
specifies an optional name which begins in column 3 and extends no further 


than column 10. 


NAMEZ®= cccccccc 
specifies a one- to eight-character alias. 


ALIAS must be preceded and followed by at least one blank. If multiple ALIAS 
statements are used, they must follow the data records. 


An ENDUP statement can be used to indicate the end of SYSIN input to this 
job step. It serves as an end-of-data indication if there is no other indication. The 


ENDUP statement follows the last group of SYSIN control statements. 
The format of the ENDUP statement is: 
Se SY SS Rt a HO Se le A I Pe i Be ie a th Te 


where: 


-/ 


is required and must appear in columns 1 and 2. 


name 
specifies an optional name which begins in column 3 and extends no further 


than column 10. 


ENDUP must be preceded and followed by at least one blank. The ENDUP 
statement must follow the last label data statement if IEBUPDTE is used to 
create output trailer labels. 


The following examples illustrate some of the uses of IEBUPDTE. Table 29 can 
be used as a quick reference guide to IEBUPDTE examples. The numbers in the 
“Example” column point to examples that follow. 


Table 29. IEBUPDTE Example Directory 


Data set 

Operation Organization Device Comments Example 
CATALOG a_ Partitioned 2314 Disks SYSUTI and SYSUT2 DD statements 
procedure define the same data set. Procedure 

to be cataloged is in the control 

data set. "I 
CREATE a Partitioned 2314 Disk Input data is in the control data set. 
partitioned Output partitioned data set is to contain 
data set three members. 2 
CREATE a Partitioned 2314 Disk Input from control data set and from 
partitioned existing partitioned data set. Output 
data set partitioned data set is to contain four 

members. 3 
UDPATE Partitioned 2314 Disk Input data set is considered to be the 
INPLACE and output data set as well: therefore, no 
renumber SYSUT2 DD statement is required. 4 
CREATE and Partitioned, 3330 Drum, Sequential master is to be created from 
DELETE Sequential 9-track tape partitioned tape input. Selected 

records are to be deleted. Blocked 

output. 5 
CREATE, Sequential, 9-track tape, Partitioned data set is to be created 
DELETE, and Partitioned 2314 Disk from sequential input. Records are to 
UPDATE be deleted and updated. Sequence 

numbers in columns other than 73 

through 80. One member ts to be 

placed in the output data set. 6 
INSERT Partitioned 2314 Disks — Block of logical records is to be 

inserted into an existing member. 

SYSUTI and SYSUT2 DD statements 

define the same data set. 7 
INSERT Partitioned 2314 Disks Two blocks of logical records are to be 

inserted into an existing member. 

SYSUT1 and SYSUT2 DD statements 

define the same data sel. 8 
CREATE Sequential Card Reader, Sequential data set with user labels is 

2314 Disk to be created from card input. 9 

COPY Sequential 2314 Disks Sequential data set is to be copied 


from one direct access volume to 
another: user labels can be processed 
by exit routines. al 10 


IEBUPDTE Example 1 


In this example, a procedure is to be placed in the cataloged procedure library, 
SYS1.PROCLIB. The example assumes that the new procedure (ERASE) can be 
accommodated within the space originally allocated to the procedure library; 
therefore, the update operation is performed directly to the old master. 


The example follows: 


//UPDATE JOB 09#660,SMITH 

re EXEC PGM=IEBUPDTE,PARM=MOD 
7/SYSPRINT "DD SYSOUT=A 

LIS TSU | DD DSNAME=SYS1.PROCLIB,DISP=SHR 
JI SYSUTZ DD DSNAME=SYS1.PROCLIB,DISP=SHR 


//SYSIN DD DATA 
y: ADD LIST=ALL,NAME=ERASE,LEVEL=01,SOURCE=0 
of NUMBER NEW1=10,INCR=10 
/ /ERASE EXEC PGM=IEHPROGM 
//DD1 DD  UNIT=190,DISP=(OLD,KEEP ), VOLUME=SER=111111 
//SYSPRINT DD  SYSOUT=A 
/* 
\ , ENDUP 
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The control statements are discussed below: 


e SYSUTI and SYSUT2 DD define the SYS1.PROCLIB data set, which is 
assumed to be cataloged. 


¢ SYSIN DD defines the control data set. The data set contains the utility 
control statements and the data to be placed in the procedure library. 


¢ The ADD Function statement indicates that records (Data statements) in the 
control data set are to be placed in the output. The newly created procedure is 
to be listed in the message data set. 


e The NUMBER Detail statement indicates that the new procedure is assigned 
sequence numbers. The first record of the procedure is assigned sequence 


number 10; the remaining two records are assigned sequence numbers 20 and 
30. 


The ERASE EXEC, DD1, and SYSPRINT DD statements are placed in the 
cataloged procedure library, SYS1.PROCLIB, as a result of this job. 


Note: The resulting procedure can be executed with an EXEC statement 
specifying PROC=ERASE. For additional information on cataloged procedures, 
see OS/VS JCL Reference, GC28-0618. 


In this example, a three-member, partitioned data set is to be created. The input 
data is contained solely in the control data set. 


The example follows: 


//UPDATE JOB “0987 70,SMILTH 

es EXEC PGM=ILEBUPDTE, PARM=NEW 

7 SISE RUNG ID SYSOUT=A 

LPS VST Z DD DSNAME=OUTLIB, UNIT=2314,DISP=(NEW,KEEP), 
// VOLUME=SER=111112,SPACE=(TRK,(50,,10)), 

// DCB=( RECFM=F, LRECL=80, BLKSTZE=80 ) 


JF SLSIN DD DATA 

of ADD NAME=MEMB1,LEVEL=00,SOURCE=0, LIST=ALL 
(Data statements, sequence numbers in columns 73 through 80) 

af ADD NAME=MEMB2, LEVEL=00,SOURCE=0,LIST=ALL 
(Data statements, sequence numbers in columns 73 through 80) 

A ADD NAME=MEMB3 , LEVEL=00 , SOURCE=0, LIST=ALL 
(Data statements, sequence numbers in columns 73 through &0) 

se ENDUP 

/* 


The control statements are discussed below: 


¢ SYSUT2 DD defines the new partitioned master OUTLIB. Enough space is 
allocated to allow for subsequent modifications without creating a new master 
data set. 


e SYSIN DD defines the control data set. The data set contains the utility 
control statements and the data to be placed as three members in the output 
partitioned data set. 


« The ADD Function statements indicate that subsequent Data statements are to 
be placed as members in the output partitioned data set. Each ADD Function 
Statement specifies a member name for subsequent data and indicates that the 
member is to be listed in the message data set. 


e The Data statements contain the data to be placed in the output partitioned 
data set. 


C 
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¢ ENDUP signals the end of control data set input. 


Note: Because sequence numbers (other than blank numbers) are included within 
the data statements, no NUMBER Detail statements are included in the example. 


In this example, a four-member, partitioned data set (NEWMCLIB) is to be 
created. The data set is to contain: 


e Two members (ATTACH and DETACH) copied from an existing partitioned 
data set (SYS1.MACLIB). 


e One replacement member (BLDL) for an existing member of the input 
partitioned data set. 


« A new member (EXIT), which is contained in the control data set. 
The example follows: 


//UPDATE JOB -O9FT/O, SMILE 

J / EXEC PGM=ITEBUPDTE,PARM=MOD 

FI SYSPRINTE DD SYSOUT=A 

FI SYSUT] DD DSNAME=SYS1.MACLIB,DISP=SHR 

Jf SL SUL? DD DSNAME=NEWMCLIB, VOLUME=SER=111112, 
i 7 DISP=(NEW; KEEP), SPACE=( TURK 4. 700,-;-102)), 

// DCB=( RECFM=F,LRECL=80,BLKSIZE=80 ) 


//SYSIN DD DATA 

Me REPRO NAME=ATTACH; LEVEL=00,SOURCE=1, LIST=ALL 
bee REPRO NAME=DETACH; LEVEL=O0)SOURCE=1, LIS T=ALL 
eA ADD NAME=EXIT, LEVEL=00, SOURCE=1, LIST=ALL 
es NUMBER NEW1=10, INCR=100 

(Data cards for EXIT member) 

7 REPL NAME=BLDL, LEVEL=01,SOURCE=1, LIST=ALL 
aah NUMBER NEW1=10, INCR=100 

(Data cards to replace BLDL member) 

A ENDUP 

/* 


The control statements are discussed below: 


e SYSUT1 DD defines the input partitioned data set SYS1.MACLIB, which its 
assumed to be cataloged. 


e SYSUT2 DD defines the output partitioned data set OUTLIB. Enough space 
is allocated to allow for subsequent modifications without creating a new 
master data set. 


e SYSIN DD defines the control data set. 


e The REPRO Function statements identify the existing input members to be 
copied onto the output data set. These members are also listed in the message 
data set. 


¢ The ADD Function statement indicates that records (subsequent Data 
statements) are to be placed as a member in the output partitioned data set. 
The Data statements are to be listed in the message data set. 


¢ The NUMBER Detail statement assigns sequence numbers to the Data 
statements.(The Data statements contain blank sequence numbers in columns 
73 through 80.) The first record of the output member is assigned sequence 
number 10; subsequent records are incremented by 100. 


e The REPL Function statement identifies a new member used as a replacement 
for an existing member. The subsequent NUMBER Detail statement assigns 
sequence numbers to the records in the new member. 
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e ENDUP signals the end of SYSIN data. 


Note: The three named input members (ATTACH, DETACH, and BLDL) do 
not have to be specified in the order of their collating sequence in the old 
master. 


In this example, a member (MODMEMB) is to be updated within the space it 
actually occupies. Two existing logical records are to be replaced, and the entire 
member is to be renumbered. 


The example follows: 


//UPDATE JOB 09#770,SMITH 

J7/ EXEC PGM=IEBUPDTE, PARM=MOD 

//SYSPRINT DD SYSOUT=A 

F7SYSUT I DD DSNAME=PDS, UNIT=2314,DISP=(OLD,KEEP), 
// VOLUME=SER=111112, 

// DCB=( RECFM=F, LRECL=80, BLKSIZE=80 ) 

J /SYSIN DD = 

so CHANGE NAME=MODMEMB, LIST=ALL, UPDATE=INPLACE 
oy NUMBER SEQ1=ALL,NEW1=10, INCR=5 


(Data statement 1, sequence number 00000020) 
(Data statement 2, sequence number 00000035) 


/* 
The control statements are discussed below: 


e SYSUT1 DD defines the data set that is to be updated in place. (Note that 
the member name need not be specified in the DD statement.) 


e SYSIN DD defines the control data set. 


e The CHANGE Function statement indicates the name of the member to be 
updated and specifies the UPDATE=INPLACE operation. The entire member 
is to be listed in the message data set. 


e The NUMBER Detail statement indicates that the entire member is to be 
renumbered, and specifies the first sequence number to be assigned and the 
increment value for successive sequence numbers. 


e The Data statements replace existing logical records having sequence numbers 
of 20 and 35. 


In this example, a sequential master data set is to be created from partitioned 
input and selected logical records are to be deleted. 


J 


The example follows: 


//UPDATE JOB 09#770,SMITH 

Va EXEC PGM=IEBUPDTE, PARM=MOD 

//SYSPRINT DD  SYSOUT=A 

//SYSUT1 DD  DSNAME=PARTDS, UNIT=3330,DISP=(OLD,KEEP), 
// NOLUME=SER=111112 

//SYSUT2 DD  DSNAME=SEQDS,UNIT=2400,LABEL=(2,SL), 

// DISP=( ,KEEP), VOLUME=SER=001234, 

// DCB=( RECFM=FB, LRECL=80, BLKSIZE=2000 ) 


JIS LSUN DD . 

ay: CHANGE NEW=PS , NAME=OLDMEMB1 
(Data statement 1, sequence number 00000123) 

of Es Pele SEQ1=223,SEQ2=246 
(Data statement 2, sequence number 00000224) 

/* 


The control statements are discussed below: 


e SYSUT1 DD defines the input partitioned data set PARTDS. Because no 
DCB parameters are specified in the SYSUT1 DD statement, the input data 
Set is assumed to consist of 80-byte, unblocked records. A warning message is 
issued to inform the user that this assumption was made. 


e SYSUT2 DD defines the output sequential data set. The data set is to be 
written as the second data set on a 9-track tape volume. The data set is 
written at a density of 800 bits per inch. 


e SYSIN DD defines the control data set. 


e CHANGE identifies the input member (OLDMEMB1) and indicates that the 
Output is to be a sequential data set (NEW=PS). 


e The first Data statement replaces the logical record whose sequence number is 
identical to the sequence number in the Data statement (00000123). If no 
such logical record exists, the Data statement is incorporated in the proper 
sequence within the output data set. 


e The DELETE Detail statement deletes logical records having sequence 
numbers from 223 through 246. 


e The second Data statement is inserted in the proper sequence in the output 
data set. 


Note: Only one member can be used as input when converting to sequential 
organization. 
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In this example, a member of a partitioned data set is to be created from 
sequential input and existing logical records are to be updated. 
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72 
//UPDATE JOB 09#770,SMITH 
// EXEC PGM=IEBUPDTE, PARM=MOD 
//SYSPRINT DD  SYSOUT=A | 
//SYSUT1 DD  DSNAME=OLDSEQDS, UNIT=2400,LABEL=( ,SL), 
// DISP=( OLD, KEEP ), VOLUME=SER=001234, 
// DCB=( RECFM=F, LRECL=80, BLKSIZE=80 ) 
//SYSUT2 DD  DSNAME=NEWPART, UNIT=2314,DISP=( ,KEEP), 
// VOLUME=SER=111112,SPACE=(TRK,(10,5,5)), 
// DCB=( RECFM=F, LRECL=80 , BLKSIZE=80 ) 
//SYSIN DD * 
sy CHANGE NEW=PO,MEMBER=PARMEM1,LEVEL=01, ave 
S SEQFLD=605 , COLUMN=40 , SOURCE=0 


(Data statement |, sequence number 00020) 

mF 2 DELETE SEQ1=220,SEQ2=250 
(Data statement 2, sequence number 00230) 

(Data statement 3, sequence number 00260) 

she ALIAS NAME=MEMB1 

/* 
The control statements are discussed below: 

e SYSUT1 DD defines the input sequential data set (OQLDSEQDS). The data set 


was originally written at a density of 800 bits per inch on a 9-track tape 
volume. 


e SYSUT2 DD defines the output partitioned data set. Enough space is allocated 
to provide for members that might be added in subsequent job steps. 


e SYSIN DD defines the control data set. 


that a conversion from sequential input to partitioned output is to be made. 
The SEQFLD parameter indicates that a five-byte sequence number is located 
in columns 60 through 64 of each Data statement. The COLUMN parameter 
specifies the starting column of a field (within subsequent data statements) 
from which replacement information is obtained. 


e The CHANGE Function statement identifies the output member and indicates ) 


e The first Data statement is used as replacement data. Columns 40 through 80 
of the statement replace columns 40 through 80 of the corresponding logical 
record. If no such logical record exists, the entire card image is inserted in the 
Output member. 


e The DELETE Detail statement deletes all of the logical records having 
Sequence numbers from 220 through 250. 


e The second Data statement, whose sequence number falls within the range 
specified in the DELETE Detail statement, is incorporated in its entirety in the 
output member. 


e The third Data statement, which is beyond the range of the DELETE Detail 
statement, is treated in the same manner as the first Data statement. 


e ALIAS assigns the alias MEMB1 to the output member PARMEM1. 
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In this example, a block of three logical records is to be inserted into an existing 
member, and the updated member is to be placed in the existing partitioned dat 
set. 


Figure 39 shows existing sequence numbers, new sequence numbers, and Data 
Statements to be inserted. veel" 
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Sequence Numbers and 
Data Statements to be 


Inserted New Sequence Numbers 
10 10 
15 15 
( . Data statement | 20 
Data statement 2 25 
Data statement 3 30 
20 35 
25 40 
30 45 


Figure 39. Sequence Numbers and Data Statements to be Inserted 


The example follows: 


//UPDATE JOB . v00¢7-/OyoM. ce 

ff EXEC PGM=IEBUPDTE, PARM=MOD 

J7S (SPRINT: DD SYSOUT=A 

Pf SVSUT 1 DD DSNAME=PDS, UNI T=2314,DISP=(OLD,KEEP), 
// VOLUME=SER=111112, 

// DCB=(RECFM=F, LRECL=80, BLKSIZE=80 ) 

{7/5 1SUT2 DD DSNAME=PDS, UNIT=2314,DISP=(OLD,KEEP), 
// VOLUME=SER=111112, 

// DCB=( RECFM=F, LRECL=80, BLKSIZE=80 } 


//SYSIN DD * 
sf CHANGE  NAME=RENUM, LIST=ALL, LEVEL=01,SOURCE=0 
a NUMBER SEQ1=15,NEW1=20, INCR=5, INSERT=YES 


(Data statement |) 
(Data statement 2) 
(Data statement 3) 


/* 
The control statements are discussed below: 

( ¢ SYSUT1 and SYSUT2 DD define the partitioned data set (PDS). 
e SYSIN DD defines the control data set. 


« The CHANGE Function statement identifies the input member RENUM. The 
entire member is to be listed in the message data set. 


« The NUMBER Detail statement specifies the insert operation and controls the 
renumbering operation. 


e The Data statements are the logical records to be inserted. (Sequence numbers 
are assigned when the Data statements are inserted.) 


In this example, the existing logical records have sequence numbers 10, 15, 20, 
25, 30, etc. Sequence numbers are assigned by the NUMBER Detail statement, 
as follows: 


1. Data statement 1| is assigned sequence number 20 (NEW1=20) and inserted 
after existing logical record 15 (SEQ1=15). 


2. Data statements 2 and 3 are assigned sequence numbers 25 and 30 (INCR=5) 
and are inserted after Data statement 1. 


3. Existing logical records 20, 25, and 30 are assigned sequence numbers 35, 40, 
and 45, respectively. 


4. The remaining logical records in the member are renumbered. 


IEBUPDTE Example 8 


In this example, two blocks (three logical records per block) are to be inserted 
( into an existing member, and the member is to be placed in the existing 
partitioned data set. A portion of the output member is to be renumbered. 
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Figure 40 shows existing sequence numbers, new sequence numbers, and Data 
statements to be inserted. 


Sequence Numbers and 
Data Statements to be 


Inserted New Sequence Numbers 
10 10 
15 1S 
Data statement | 20 
Data statement 2 25 
Data statement 3 30 
20 35 
25 40 
30 45 
Data statement 4 50 
Data statement 5 op, 
Data statement 6 60 
35 65 
Data statement 7 70 
40 75 
50 80 
150 150 
155 155 


Figure 40. Sequence Numbers and Seven Data Statements to be Inserted 


The example follows: 


/ /UPDATE JOB; U9G7/04 SMITH 

ff EXEC PGM=IEBUPDTE, PARM=MOD 

tf S1SPR LNT DD SYSOUT=A 

J PotSUT DD DSNAME=PDS, UNIT=2314,DISP=( OLD,KEEP), 
// VOLUME=SER=111112, 

// DCB=(RECFM=F,BLKSIZE=80, LRECL=80 ) 

PP SVSIT2 DD DSNAME=PDS, UNI T=2314,DISP=(OLD,KEEP), 
// VOLUME=SER=111112, 

// DCB=( RECFM=F, LRECL=80,BLKSIZE=80 ) 


77 SVSIN DD 43 
eye CHANGE NAME=RENUM, LIST=ALL, LEVEL=01,SOURCE=0 
wa NUMBER SEQ1=15,NEW1=20, INCR=5, INSERT=YES 


(Data statement |) 
(Data statement 2) 
(Data statement 3) 


Pa NUMBER SEQ1=30, INSERT=YES 


(Data statement 4) 
(Data statement 5) 
(Data statement 6) 
(Data statement 7, sequence number 00000038) 


/* 
The control statements are discussed below: 

e SYSUT! and SYSUT2 DD define the partitioned data set PDS. 
« SYSIN DD defines the control data set. 


e The CHANGE Function statement identifies the input member RENUM. The 
entire member is to be listed in the message data set. 


« The NUMBER Detail statements specify the insert operations 
(INSERT=YES) and control the renumbering operation. 


e Data statements 1, 2, 3, and 4, 5, 6 are the blocks of logical records to be 
inserted. Because they contain blank sequence numbers, sequence numbers are 
assigned when the Data statements are inserted. 


e Data statement 7 is a logical record to be inserted in the output member. 
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The existing logical records in this example have sequence numbers 10, 15, 20, 
25, 30, 35, 40, 45, 50, 150, 155, 160, 165, etc. The insert and renumbering 
operations are performed as follows: 


1. Data statement 1 is assigned sequence number 20 (NEW1=20) and inserted 
after existing logical record 15 (SEQ1=15). 


2. Data statements 2 and 3 are assigned sequence numbers 25 and 30 (INCR=5) 
and are inserted after Data statement 1. 


3. Existing logical records 20, 25, and 30 are assigned sequence numbers 35, 40, 
and 45, respectively. 


4. Data statement 4 is assigned sequence number 50 and inserted. (The 
SEQ1=30 specification in the second NUMBER statement places this data 
Statement after existing logical record 30, which has become logical record 
45.) 


5. Data statements 5 and 6 are assigned sequence numbers 55 and 60 and are 
inserted after Data statement 4. 


6. Existing logical record 35 is assigned sequence number 65. 
7. Data statement 7 is assigned sequence number 70 and is inserted. 


8. The remaining logical records in the member are renumbered until logical 
record 150 is encountered. Because this record has a sequence number higher 
than the next number to be assigned, the renumbering operation is terminated. 


In this example, IEBUPDTE is used to create a sequential data set from card 
input. User header and trailer labels, also from the input stream, are placed on 
this sequential data set. 


The example follows: 


// LABEL JOB ,MSGLEVEL=1 
//CREATION EXEC PGM=IEBUPDTE, PARM=NEW 
//SYSPRINT DD  SYSOUT=A 

//SYSUT2 DD  DSNAME=LABEL, VOLUME=SER=123456, 
// DISP=(NEW,KEEP),LABEL=(,SUL), 

// SPACE=(TRK,(15,3)),UNIT=2314 

//SYSIN DD * 

oy) LABEL 


(First header label) 

(Last header label) 

“af ADD LIST=ALL, OUTHDR=ROUTINE1 , OUTTLR=ROUTINE2 
(First input data record) 

(Last input data record) 

a LABEL 


(First tratler label) 
(Last trailer label) 


oe ENDUP 
/* 
The control statements are discussed below: 


e SYSUT2 DD defines and allocates space for the output sequential data set, 
which resides on a 2314 volume. 


e SYSIN DD defines the control data set. (This control data set includes the 
sequential input data set and the user labels, which are on cards.) 
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¢ The first LABEL statement identifies the 80-byte card images in the input 
stream which will become user header labels. (They can be modified by the 
user’s header-label processing routine specified on the ADD Function 
Statement.) 


¢ The ADD Function statement indicates that the Data statements that follow a 
are to be placed in the output data set. The newly created data set is to be 
listed in the message data set. User output header and output trailer routines 
are to be given control prior to the writing of header and trailer labels. 


e The second LABEL statement identifies the 80-byte card images in the input 
stream which will become user trailer labels. (They can be modified by the 
user trailer-label processing routine specified on the ADD Function statement. ) 


e ENDUP signals the end of the control data set. 


In this example, IEBUPDTE is used to copy a sequential data set from one direct 
access volume to another. User labels are processed by user exit routines. 


The example follows: 


7 
//LABELS JOB ,MSGLEVEL=1 
Jf EXEC PGM=IEBUPDTE, PARM=( MOD, ,MMMMMM ) 
//SYSPRINT DD  SYSOUT=A 
//SYSUT1 DD  DSNAME=OLDMAST,DISP=OLD,LABEL=(,SUL), 
// JOLUME=SER=111111,UNIT=2314 
//SYSUT2 DD  DSNAME=NEWMAST,DISP=(NEW,KEEP),LABEL=(,SUL), 
// UNIT=2314, VOLUME=SER=XB182, 
// SPACE=(TRK,(5,10)) 
//SYSIN DD DSNAME=INPUT,DISP=OLD,LABEL=(,SUL), 
// VOLUME=SER=222222,UNIT=2314 


7 J 
(Input data set) 


=f REPRO  LIST=ALL,INHDR=SSSSSS,INTLR=TTTTTT, 4c 
./ OUTHDR=XXXXXX , OUTTLR=YYYYYY 
ef ENDUP 


The control statements are discussed below: 


e SYSUT1 DD defines the input sequential data set, which resides on a 2314 
volume. 


¢ SYSUT2 DD defines the output sequential data set, which will reside on a 
2314 volume. 


e SYSIN DD defines the control data set. 


e The REPRO Function statement indicates that the existing input sequential 
data set is to be copied to the output data set. This output data set is to be 
listed on the message data set. The user’s label processing routines are to be 
given control when header or trailer labels are encountered on either the input 
or the output data set. 


e ENDUP indicates the end of the control data set. 


IEHATLAS is a system utility used when a defective track is indicated by a data 
check or missing address marker condition. (See “Introduction’’ for general 
system utility information. ) 


IEHATLAS can be used to locate and assign an alternate track to replace the 
defective track. Usable data records on the defective track are retrieved and 
transferred to the alternate track. The bad record from the defective track is then 
replaced on the alternate by a correct copy provided by the user. 


In a simple application, IEHATLAS is used as a separate job after an abnormal 
termination of a problem program. Input data necessary for execution of 
IEHATLAS—the address of the defective track and replacement records—may 
be obtained from the dump and from backup data. 


A more complex use of IEHATLAS may involve the preparation of a user’s 
SYNAD routine, which reconstructs the necessary input data and invokes 
IEHATLAS dynamically. 


When IEHATLAS is invoked, it attempts to write on the defective track. If the 
subsequent read-back check indicates that the attempt was successful, a message 
is issued on the SYSOUT device. If not, a supervisor call routine (SVC 86) is 
entered automatically. 


The SVC routine locates and assigns an alternate track. (If a defective track 
already has an alternate and an error occurs on that alternate, the SVC routine 
assigns the next available alternate. All of the valid data records on the defective 
track are retrieved and transferred to the alternate track. The input record is 
written on the alternate track in the correct position to recover from the previous 
error. 


When a READ error occurs and a complete recovery is desired, IEHDASDR can 
be used to produce a listing of error data on a track. Using this data, the input 
data record for IEHATLAS can be created. The replace function can then be 
performed by executing IEHATLAS. 


The direct access device types supported by IEHATLAS are the 2305, 2314, 
2319, and 3330. 


Input and Output 


IEHATLAS uses the following input: (1) a description of the defective track, 
specifying the cylinder, track, record, key, and data length (in hexadecimal 
notation), (2) an indication if WRITE Special is needed, and (3) a valid copy (in 
hexadecimal notation) of the bad record. 


IEHATLAS produces as output: (1) a message, issued on the SYSOUT device, 
containing the user’s control information, the input record, and diagnostics, (2) 
the input record, written on either the original (defective) track or on an 
alternate track containing the usable data taken from the defective track, and (3) 
the return parameter list (specifying a maximum of three error record numbers in 
hexadecimal when an unrecoverable error occurs). 


Control 


IEHATLAS is controlled by job control statements and utility control statements. 
The job control statements are used to execute or invoke IEHATLAS and to 


define the data sets used and produced by IEHATLAS. 
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Job Control Statements 


Restrictions 


A utility control statement is used to specify whether the bad record is a member 
of the volume table of contents or a member of some other data set. It is also 
used to indicate whether or not the WRITE Special command is to be used. 


Table 30 shows the job control statements necessary for using IEHATLAS. 
Table 30. IEHATLAS Job Control Statements 


Statement Use 
JOB Initiates the job. 


EXEC Specifies the program name (PGM=IEHATLAS) or, if the job control 
statements reside in a procedure library, the procedure name. 


SYSPRINT DD Defines a sequential data set that contains the output messages issued by 


IEHATLAS. 
SYSUT1 DD _ Defines the data set that contains the bad record. 
SYSIN DD Defines the control data set, which contains the utility control statement and a 


copy of the bad record. 


e The block size for the SYSPRINT data set must be a multiple of 121. The 
block size for the SYSIN data set must be a multiple of 80. Any blocking 
factor can be specified. 


e DISP=SHR must not be coded on the SYSUT1 DD statement. 


Utility Control Statement 


TRACK or VTOC Statement 
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The TRACK or VTOC control statement is used to control IEHATLAS. 


The TRACK or VTOC statement is used to identify the defective record. 
The format of the TRACK or VTOC statement is: 


where: 
TRACK= 
specifies that an alternate track is to be assigned for a track that does not 
contain VTOC records. 
VTOC= 
specifies that an alternate track is to be assigned for a track that contains 
VTOC records. 


bbbb 
This number must be padded with zeros. 


CECE 
is the number of the cylinder in which the defective track was found. 


hhhh 
is the defective track number. 


rrkk 
is the record number and key length for the bad record. 
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dddd 


is the data ene of the bad record. Mydiies a ee Special command is 
used, dddd is the length of the record segment.) 


S 
is an optional byte of EBCDIC information that specifies that the WRITE 
Special command is to be used (when the last record on the track overflows 
and must be completed elsewhere). 


Care should be taken to ensure that the input record data length does not exceed 
the track size. This is especially important when the WRITE Special command is 
specified because the error may not be recognized immediately by the system. 


The TRACK or VTOC statement must not begin in column 1. 


Input data (consisting of the hexadecimal replacement record) begins in column 1 
immediately following the utility control data. Input data may continue through 
column 80. As many cards as necessary may be used to contain the replacement 
record. All columns (1 through 80) are used on the additional cards. 


IEHATLAS is designed to replace an error record with a copy of that record. It 
cannot be used to replace a record with another of a different key and/or data 
length. 


An end-of-file record cannot be changed; therefore, input for key and/or data 
fields are ignored. 


The following examples illustrate some of the uses of IEHATLAS. Table 31 can 
be used as a quick reference guide to IEHATLAS examples. The numbers in the 
‘Example’ column point to examples that follow. 


Table 31. IEHATLAS Example Directory 


Operation Comments Example 
Get Alternate Write Special is tncluded because of a 

Tracks track overflow condition. | 

Get Alternate Alternate track assigned for a bad 

Track end-of-file record. 2 

Get Alternate Alternate track assigned for a bad 

Track VTOC record. 3 

Get Alternate Replace defective record zero. 

Track 4 


In this example, the data set defined by SYSUT1 contains the bad record. An 
alternate track on the specified unit and volume will be assigned to replace the 
defective track. 


The example follows: 


//JOBATLAS JOB 06#990,SMITH,MSGLEVEL=1 

fi SLEP EXEC PGM=IEHATLAS 

SE SYISPRINE -DD SYSOUT=A 

J /SYSUT DD DSNAME=NEWSET, UNI T=3330,VOLUME=SER=333011, 
// DISP=OLD 

LpotaiN DD - 

TRACK=O00000002000422020006S 

PSP 1G2ZC2FORPU0000 


/* 
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The control statements are discussed below: 


¢ SYSPRINT DD defines the device to which the output messages can be 
written. 


« SYSUT1 DD defines the data set that contains the bad record. The devices 
supported are 2305, 2314, 2319, and 3330. 


e SYSIN DD defines the control data set, which follows in the input stream. 


¢ TRACK specifies the cylinder and track number for the defective track, and 
the record number, key length, and data length of the bad record. In this 
example, the input record is to be placed on cylinder two, track four, record 
22; and it has a key length of two with a logical record length of six. The 
WRITE Special (S) character is used because there is a track overflow 
condition. 


The input record in this example is a typical hexadecimal record as defined by a 
TRACK statement. The input record contains eight bytes (data length = 6, key 
length = 2). 


IEHATLAS Example 2 


In this example, an alternate track is assigned for a bad end-of-file record. 
The example follows: 


//JOBATLAS JOB 06#990,SMITH,MSGLEVEL=1 

//STEP EXEC PGM=IEHATLAS 

//SYSPRINT DD  SYSOUT=A 

//SYSUT1 DD  DSNAME=EOFSET, UNIT=2305,VOLUME=SER=33333, 
// DISP=OLD 


//SLSIN DD * 
TRACK=00000001000003000000 
/¥* 


The control statements are discussed below: 


e SYSPRINT DD defines the device to which the output messages can be 
written. 


e SYSUT1 DD defines the data set that contains the bad record. 
e SYSIN DD defines the control data set, which follows in the input stream. 


¢ TRACK defines an end-of-file record on cylinder one, track zero, record 
three. Input data other than the utility control statement is not required. 


IEHATLAS Example 3 


In this example, an alternate track is assigned for a bad volume table of contents 
record. 


The example follows: 


//JOBTALAS JOB 06#990,SMITH,MSGLEVEL=1 

Jf STEP EXEC PGM=IEHATLAS 

{(SYSERINT DD SYSOUT=A 

f7#STSUT DD UNTT=2314, VOLUME=SER=22222,DISP=OLD 
(7 SY SLN DD * 

VTOC=000000000005022C0060 
D6C2D1C5C3E340404040404040404040404040404040404040404040404040404040404040404040 
40404040F 1F2F3F1F1FO0F00001440136000000010000000000000000000000000000000000000000 
QO0040008000000F 000F0003 33333 33333333333310DDD00000 1000 00A0000000ADDND0NN0N000000 
Oleleteteleleretelelerelelelelelelelelelerelelelerelelelerelelelerelelerererere) 

/* 
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U 


IEHATLAS Example 4 


The control statements are discussed below: 


e SYSPRINT DD defines the device to which the output messages can be 
written. 


e SYSUT1 DD defines the data set that contains the bad record. 
e SYSIN DD defines the control data set, which follows in the input stream. 


e VTOC defines the location of the bad VTOC record as track five of cylinder 
zero. The record number is 2 with a key length of 44. Record length of the 
bad record is 96. 


The input record in this example is a:typical hexadecimal record as defined by 
the VITOC statement. The input record contains 140 bytes (data length = 96, 
key length = 44). 


In this example, the replacement record is Record 0. 
The example follows: 


//JOBATLAS JOB 06#990,SMITH,MSGLEVEL=1 


//STEP EXEC PGM=IEHATLAS 

//SYSPRINT DD SYSOUT=A 

JZ SYSUT I DD DSNAME=NEWSET, UNIT=3330, 

// VOLUME=SEr=333001,DISP=OLD 

{/SYSIN DD * 
TRACK=O00000002000400000008 

OOO0000000000000 

/* 


The control statements are discussed below: 


e SYSPRINT DD defines the device to which the output messages can be 
written. 


e SYSUT1 DD defines the data set that contains the bad record. 
e SYSIN DD defines the control data set, which follows in the input stream. 


¢ TRACK specifies the bin, cylinder, and track number for the defective track, 
and the record number, key length, and data length of the bad record. In this 
example, the input record has a bin number of zero because the device is a 
3330; it is to be placed on cylinder two, track four, record zero; and it has a 
key length of zero with a logical record length of eight. The input record in 
this example is a typical hexadecimal record as defined by a TRACK 
Statement. The input record contains eight bytes (data length=8, key 
length=0). 
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IEHDASDR Program 


= IEHDASDR is a system utility used to prepare direct access volumes for use and 
to ensure that any permanent hardware errors (that is, defective tracks) incurred 
on direct access volumes do not seriously degrade the performance of those 


volumes. (See “Introduction” for general system utility information.) 


In addition, IEHDASDR can be used to dump the entire contents or portions of 
a direct access volume to a volume or volumes of the same direct access device 
type, to a tape volume or volumes, or to a system output device. Data that is 
dumped to a magnetic tape volume is arranged so that it can subsequently be 
restored to its original organization by IEHDASDR. The direct access device 
types supported by IEHDASDR are: 2305, 2314, 2319, and 3330. 


The program can be used to: 


e Analyze tracks, assign alternate tracks for defective tracks, and perform 
housekeeping and formatting functions to make direct access volumes, with the 
exception of the 3330, suitable for operating system use. 


Note: Defective tracks are flagged when a 3330 is initialized at the factory. An 
IEHDASDR job to initialize a 3330 will not perform a surface analysis. The 
ANALYZE option performs a “quick-DASDI” (see Table 32) which includes: 


e Initialization of track zero including IPL1, IPL2, volume label, and optional 
IPLTXT. 


e VTOC construction. 


e Perform housekeeping and formatting functions on direct access volumes 
L without analyzing tracks. 


¢ Change the volume serial number of a formatted direct access volume. 


¢ Assign alternate tracks for specified defective or questionable tracks on disk 
volumes. 


¢ Create a backup or transportable copy of a direct access volume, or list the 
contents on a system output device. 


e Copy dumped data from a tape volume to a direct access volume. 


¢ Write IPL records and a program on a direct access volume. 


Initialize—W/ith Recording-Surface Analysis 


IEHDASDR can be used to analyze the recording surface of a direct access 
device to: 


- Assign alternate tracks for any disk tracks found defective during an analysis, 
or for any track previously flagged defective. Each track can be analyzed 
from 1 to 255 times, at the discretion of the user. The test of looking for 
previously flagged tracks must be suppressed when a new or non-formatted, 
direct access volume is being initialized. 


e Standardize each track by placing a standard home address and a record zero 
(RO) field on it. The remainder of the track is erased. 


¢ Construct IPL bootstrap records (records 1 and 2 of track 0), a volume label 
record (record 3 of track 0), and a volume table of contents (VTOC), whose 
( size and placement are determined by the user. 
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¢ Optionally write an IPL program record for 2305, 2314, 2319, and 3330 
volumes and provide owner information in the volume label record. 


Figure 41 shows a direct access volume after it has been prepared for use. A 
direct access volume can be initialized in this manner using IEHDASDR. 


Standard home 
address 


Track 0 ed 

Track 1 IPL 
bootstrap 

Track 2 


records 
Volume 
label 
record 


Figure 41. Direct Access Volume Initialized Using IEHDASDR 


Initialize—Without Recording-Surface Analysis 


JIEHDASDR can be used to prepare a direct access volume for use without 
performing a recording-surface analysis. 


A volume might be prepared for system use without recording-surface analysis 
to: 


e Check a direct access volume for previously flagged tracks. No formatting is 
performed on known defective tracks. 


e Standardize each track by placing a standard home address and a record zero 
(RO) field on it. The remainder of the track is erased (except on 3330 
volumes). 


e Construct IPL bootstrap records (records 1 and 2 of track 0), a volume label 
record (record 3 of track 0), and a volume table of contents (VTOC), whose 
size and placement are determined by the user. 


e Optionally write an IPL program record for 2305, 2314, 2319, and 3330 
devices, and provide owner information in the volume label record: 
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Changing the Volume Serial Number of a Direct Access Volume 


[EHDASDR can be used to change the volume serial number of an initialized 

direct access volume. Opti nally, a one- to ten-character owner name can be 

placed in the volume label record (record 3 of track 0). If an owner name 
C already exists, it is overwritten with the new name. 


Note: All cataloged data sets residing on a volume whose label is changed must 
be recataloged, if the catalog reflects the old serial number. 


Assigning Alternate Tracks for Specified Tracks 


IEHDASDR can be used to assign an alternate track on a disk volume. An 
alternate track can be assigned for any track, whether it is defective or not. If 
the specified track is an alternate, a new alternate is assigned; if the specified 
track is an unassigned alternate, it is flagged to prevent its future use. 


Creating a Backup, Transportable, or Printed Copy 


IEHDASDR can be used to dump a direct access volume or a portion of a 
volume to any number of tape volumes or volumes of the same direct access 
device type, or to a system output device. The program can dump a single track, 
a group of tracks, or an entire volume. 


When an entire volume is dumped: 


e All primary tracks (for which no alternate tracks are assigned) are dumped. 


e When a primary track is found to have an alternate track assigned, the 
alternate is dumped in place of the primary. 


Each track to be dumped will have all of its data except the home address and 
the count field of record zero (RO) copied to the receiving volume. 


A receiving direct access volume retains its own serial number unless the user 
( specifies that it is to be assigned the serial number of the direct access volume 
being dumped. 


Except for a printing operation, only data that is owned is dumped; IEHDASDR 
checks the first or only Free Space (Format 5) data set control block (DSCB) in 
the volume table of contents. The Free Space (Format 5) DSCB identifies 
unowned (unused) space on the direct access volume. Whenever an unowned 
track is encountered, a dummy record, containing a home address and record 
zero, iS written on the receiving volume. When data is dumped to a system 
output device, the entire range of specified tracks is dumped. 


A printing operation prints each record in hexadecimal. In addition, all printable 
characters are also represented in EBCDIC. 


Figure 42 shows the format of printed output. Each track is identified by its 
absolute track address (cccchhhh). The RO data field is printed on the same line 
as the track address. Each printed record is preceded by a count field that 
identifies the applicable track address (cccchhhh), the record number of the 
record being printed (rr), and the key and data length (kk and dddd) of the 
record. 
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*#* TRACK cccchhhh 


COUNT cccchhhhrrkkdddd 


000000 
000032 

COUNT  cccechhhhrrkkdddd 
000000 
000032 
*** TRACK cccchhhh 


COUNT ecccchhhhrrkkdddd 


000000 


000032 XXXKXXXX XXXXXKXXXX etc. 


RO DATA XXXXXXXXXXXXXXXX 


key and data fields 


(hexadecimal) 


XXXXXXXX XXXXXXXX XXXXXXXKX XXRXXXXXX 
XXXXXXXKX XXXXXXXKX KXXKXXKXKXXKX XXXXXXXXK 


XXXXXXXX XKXXXXXXX XXRXXXXXX KXXRXXXXXX 
XXXXXXXX XXXXXXXX XXXXXXXX Etc. 


RO DATA XXXXXXXXXXXXXXXX 


XXXXXXXX XXXXKXXKKX KRXKXXXXXKX XXXXXXXX 


key and data fields 
(EBCDIC) 
XXXXXXXX XXXXXXXX XXXXXKXXKX XXXXXXXX 


AXXXXXKXX XXAXXAXAKXKX XKXXKAXXKK KXAXKAXKXXX 
etc. 


XXXXXXXX XXXXXXXX XXXXKXXXX XXXKXXXXX 


AXXXAXXXKX KXXXXXXXX XKXXRXXKXXK KXXXAXXAXAKX 


Figure 42. Format of a Direct Access Volume Dumped to a Printer Using IEHDASDR 


If an alternate track is printed in place of a primary track, it is identified in the 
printout by the primary track address. 


Copying Dumped Data to a Direct Access Volume 


When a direct access volume is dumped to a tape volume, the data is placed in a 
format that is specially suited for the tape volume. IEHDASDR can be used to 
restore the format of the dumped data and place the data on the same type of 
direct access volume as the original volume; that is, data originally dumped from 
a 2314 volume can be restored to a 2314 volume, etc. 


Identical copies of dumped data can be restored to any number of volumes of the 
Same direct access device type as the original volume during the execution of a 
single restore operation. In addition, data that was dumped by IBCDMPRS can 
be restored. 


A receiving direct access volume retains its own serial number unless the user 
specifies that it is to be assigned the serial number of the direct access volume 
originally dumped. If multiple direct access volumes are to be dumped to, and the 
user specifies that the serial number of the dumped volume is to be propagated, 
all receiving volumes are assigned that serial number. 


Writing IPL Records and a Program on a Direct Access Volume 
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IEHDASDR can be used to write IPL bootstrap records and a program on 
cylinder O, track O or an initialized 2305, 2314, 2319, or 3330 volume. Any 
online volume other than the system residence volume can be used. 


The contents of the IPL records and the contents of the records that make up 
the program are not checked by IEHDASDR. It is the user’s responsibility to 
ensure that the IPL records can load an executable program. 


The first IPL record must contain a PSW followed by two CCWs (channel 
command words). The CCWs must have the following hexadecimal formats: 


First CCW: 06xxxxxx60000090 
Second CCW: O8xxxxxx00000000 


The first CCW is a command to read in the second IPL record at main storage 
address xxxxxx. The second CCW is a transfer-in-channel command (a branch) 
to the CCW that begins the second IPL record. 


J 


The second IPL record must be a 144-byte channel program. Bytes 32 to 42 of 
this record must contain zeros. 


The program may consist of: 

e One record, not longer than 3K (3072) bytes. 

¢ Two records, neither longer than 3K (3072) bytes. 
¢ Three records, none longer than 2K (2048) bytes. 


Figure 43 shows an input data set with three program records. 


IPL 
Records Program Records 


K 
2K bytes 2K bytes Bytes 


24 bytes 


Figure 43. Input Data Set with Three Program Records 


If the output volume does not contain user labels, IEHDASDR writes program 
records after the volume label record. Figure 44 shows where program records 
are written when the output volume does not contain user labels. 


Writes Program Record Here 


Figure 44, Cylinder 0, Track 0 Fragment Without User Labels 


If user labels have been written after the volume label, the user can specify that 
IEHDASDR: 


e Write over the user labels. 


¢ Put the program records after the user labels when a 2305 or 3330 volume is 
used. 


Figure 45 shows program records to be written after user labels. 


Writes Program Records Here 


Figure 45. Cylinder 0, Track 0 Fragment with User Labels 
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Input and Output 


Control 


Job Control Statements 
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The following errors are possible when using IEHDASDR to write IPL records 
and a program on a direct access volume: 


e A 2314 or 2319 output volume contains user labels, but the user has not 
specified that the user labels are to be overwritten. 


e The total input (IPL records and program) consists of fewer than three 
records. 


e The first and second IPL records are not 24 bytes and 144 bytes in length, 
respectively. 


¢ A third program record is longer than 2K bytes. 
e The output device is not a direct access device. 
e The output volume contains a VEOC on cylinder 0, track 0. 


¢ The output volume is the system residence volume. 


IEHDASDR uses as input a control data set containing utility control statements, 
and optionally, IPL text. 


The primary output or result of executing IEHDASDR is determined by the 
application. 


A sequential message data set is created to list informational messages (for 
example, control statements used), dumped data (for a print operation), and any 
error messages. 


IEHDASDR provides a return code to indicate the results of program execution. 
The return codes and their meanings are: 


e 00, which indicates successful completion. 


e 04, which indicates that an unusual condition was encountered; however, the 
overall result is successful. A warning message is issued. 


e 08, which indicates that a specified operation did not complete successfully. 
An attempt is made to perform any additional operations. 


e 16, which indicates that either an error occurred upon invoking IEHDASDR, 
or IEHDASDR was unable to open the input or message data set. The job step 
is terminated. 


IEHDASDR is controlled by job control statements and utility control 
statements. The job control statements are used to execute or invoke 
IEHDASDR and define the data sets used and produced by IEHDASDR. 


The utility control statements are used to control the functions of the program. 


Table 32 shows the job control statements necessary for using IEHDASDR. 


Table 32. IEHDASDR Job Control Statements 


Statement Use 
JOB Initiates the job. 
EXEC Specifies the program name (PGM=IEHDASDR) or, if the job control 


statements reside in a procedure library, the procedure name. Additional 
information can be entered in the PARM parameter of the EXEC 
statement; see ““‘PARM Information on the EXEC Statement” below. 


SYSPRINT DD _ Defines a sequential message data set. The data set can be written toa 
system output device, a tape volume, or a direct access device. 


anyname DD Defines a direct access device type. 
tapename DD Defines a magnetic tape unit. 
SYSIN DD Defines the control data set. The control data set usually resides in the 


input stream; however, it can be defined as a blocked or unblocked 
sequential data set or as a member of a procedure library. 


The “‘anyname” DD statement can be entered: 
//anyname DD UNIT=xxxx,VOLUME=SER=xxxxxx, DISP=OLD 


If more than one volume is to be processed on a single mountable device, 
deferred mounting can be specified in the ‘‘anyname’”’ DD statement by entering: 


//anyname DD UNIT=(xxxx,, DEFER), VOLUME=(PRIVATE....), 
ps DISP=(NEW,KEEP) 


The “‘anyname” DD statement is not used for an operation that analyzes an 
offline direct access volume. 


If the volume serial number of a volume to be processed online is not known, it 
may be possible to make a non-specific, PRIVATE volume request on a specific 
unit; for example: 


//anyname DD UNIT=(191,, DEFER), VOLUME=PRIVATE,DISP=(NEW,KEEP), 
// SPACE=(TRK,(1,1)) 


In this case, the operator is asked to mount a scratch volume on that unit. See 
‘Appendix C: Defining Mountable Devices” for the appropriate DD statement 
and for a discussion of how to make a non-specific unit request. 


If an IEHDASDR operation produces a volume serial number that is a duplicate 
of a volume serial number already allocated within the system, the volume to 
which the duplicate number is assigned is made unavailable to the system. The 
operator is asked to remove the applicable volume at the completion of the 
Operation. 


The ‘‘tapename”’ DD statement can be entered: 


//tapename DD UNIT=xxxx, VOLUME=SER=xxxxxx, LABEL=(...,...), 
f/f DISP=(...,KEEP), DCB=(TRTCH=C, DEN=x) 


If more than one tape volume is to be processed on the same tape unit, deferred 
mounting can be specified by: 


//tapename DD UNIT=(xxxx,, DEFER), VOLUME=(PRIVATE.,...) 
If standard-labeled tapes are specified, the DSNAME should also be provided. 


The ‘“‘anyname”’ DD and ‘‘tapename’’ DD statements are referred to by utility 
control statements for program operation. 


Both the SYSIN and the SYSPRINT data set can have a blocking factor of other 
than 1. 
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Data can be dumped from the system residence volume (the IPL volume); 
however, this is the only IEHDASDR operation that can be performed on that 
volume. 


Because JIEHDASDR can change serial numbers and existing data on a direct 
access volume, operating precautions must be followed by users who have two or 
more central processing units sharing the same direct access volume. 


If IEHDASDR is run in a multiprogramming environment, the user must choose 
a combination of DD statements (defining mountable devices) that will ensure 
that volume integrity is maintained. Refer to “Appendix C: DD Statements for 
Defining Mountable Devices.” 


If password-protected data sets reside on volumes that are used by IEHDASDR, 
the following considerations must be made: 


e When dumping from a volume containing password-protected data sets, each 
data set must be described in a separate DD statement having a unique 
ddname. When the program is executed, the operator must supply the correct 
password (in answer to a console message) for each password-protected data 
set. 


e When dumping to a tape volume from a direct access volume containing 
password-protected data sets, the DD statement defining the tape volume must 
include a DSNAME parameter. In addition, the LABEL parameter must 
define a standard-labeled tape, include a PASSWORD subparameter, and 
specify or imply a file number of 1. 


¢ When restoring from a tape volume, a DSNAME parameter must be included 
in the DD statement defining the tape volume. 


« During the DUMP, RESTORE, ANALYZE, and FORMAT functions (see 
“Utility Control Statements’’), the direct access ““TO”’ volume is checked for 
password-protected data sets. At this time the operator must supply the 
correct password for each password-protected data set encountered. JZ 


Refer to VS Data Management for System Programmers , GC28-0631, for 
additional information on password protection. 


IEHDASDR can perform up to six concurrent operations of ANALYZE, 
FORMAT, DUMP, or RESTORE operations (see ‘‘Utility Control Statements’’). 
This feature, which can shorten the time required to execute the program, is 
controlled by (1) the number of devices defined for use and (2) the physical 
arrangement of utility control statements in the input stream. For example, 
assuming that the required devices are defined and available, a combination of six 
successive statements of the same type permits six concurrent operations to take 
place. However, if the utility control statements are arranged so that no 
operations of the same type appear in succession, no operations are performed 
concurrently, even though many devices might be defined for use. 


Note: The number of concurrent operations allowed can be overridden by an 
EXEC statement PARM value. 


e If IEHDASDR is used to change a volume serial number and a subsequent 
operation is performed on the newly labeled volume in the same job step, two 
‘‘anyname”’ DD statements are required. The VOLUME parameter in the first 
statement includes the old volume serial number; the VOLUME parameter in 
the second statement specifies the new volume serial number. In addition, the 
second statement specifies unit affinity with the first. 


e One “‘anyname” DD statement is required for each device to be used in the 
job step unless the device is to be processed off line. 


e The “tapename” DD statement must be included if a data set is dumped to 
tape or if a previously dumped data set is to be restored to a direct access 
volume. 


e If BLKSIZE is specified on the SYSIN DD statement, it must be a multiple of 
80. If BLKSIZE is omitted from the statement, a block size of 80 bytes is 
assumed. 


¢« If BLKSIZE is specified on the SYSPRINT DD statement, it must be a 
multiple of 121. If BLKSIZE is omitted or incorrectly specified, a block size 
of 121 bytes is assumed. 


e SYSIN attributes must be identical if SYSIN data sets are to be concatenated. 


PARM Information on the EXEC Statement 


The EXEC statement for IEHDASDR can contain PARM information that is 
used by the program to control line density on output listings and to indicate the 
maximum number of operations of the same type that can be performed 
concurrently in the job step. 


The EXEC statement can be coded: 


// EXEC PGM=IEHDASDR{,PARM='Nen’ } 
{,PARM='LINECNT=xx’ } 
{,PARM=LINECNT=xx,N=n } 


The LINECNT value specifies the number of lines per page in the listing of the 
SYSPRINT data set. The number xx is a 2-digit decimal number ranging from 
01 to 99. If LINECNT is omitted, the number of lines per page is 58. 


The N value specifies a decimal number from one to six that represents the 
maximum number of like functions that can be performed concurrently by 
IEHDASDR, assuming that adequate system resources are available. See 
OS/VS1 Storage Estimates, GC24-5094, or OS/VS2 Storage Estimates, 
GC28-0604, for the storage required for each operation. If N is omitted, 

up to six ANALYZE, FORMAT, DUMP, or RESTORE operations are performed 
concurrently—according to the number of successive like statements in the 

input stream. (See ‘“‘Utility Control Statements.’’) 


System resources permitting, multiple output copies can be specified in any or all 
of the concurrent operations. 


For example, if N=2 and four DUMP statements appear in succession, the first 
two dump operations are performed concurrently. As each dump operation is 
completed and system resources become available, a new dump operation begins. 


Utility Control Statements 
The utility control statements used to control IEHDASDR are: 


e ANALYZE statement, which is used to analyze the recording surface to test 
for defective tracks, assign alternates for any defective tracks found, and 
format the volume to make it ready for use. 


e FORMAT statement, which is used to make a volume ready for use without 
performing an analysis of the recording surface. 


« LABEL statement, which is used to change the volume serial number of a 
direct access volume and, optionally, to update the owner field. 
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¢ GETALT statement, which is used to assign an alternate track for a specified 
track. 


e DUMP statement, which is used to dump a single track, a group of tracks, or 
an entire direct access volume. 


e RESTORE statement, which is used to restore a previously dumped direct ) 
access volume to a direct access device. 


« IPLTXT statement, which signals the beginning of IPL program text 
statements. 


¢ PUTIPL statement, which specifies that IPL records and a program are to be 
written on a direct access device. 


For most operations, multiple copies of a source volume can be made. The 
program can also perform from two to six ANALYZE, FORMAT, DUMP, or 
RESTORE operations concurrently, according to the number of successive like 
statements in the input stream; that is, up to six direct access volumes can be 
analyzed or formatted, or dumped simultaneously, or up to six magnetic tape 
(restore) volumes can be processed simultaneously. 


ANALYZE Statement 


The ANALYZE statement is used to analyze the recording surface of a direct 
access device. Bit patterns are written on a track, read, and tested for defects. If 
no defects are found, the track is formatted to make it ready for system use. 


The format of the ANALYZE statement is: 


S q i eet, ae ee ob 
~~ £ Pe Srade \° 7s ee 
s om ee gees ST ul : 
Here, ey e . aah, am 4; 4 


£ Lo 


TODD= 
specifies the volume to be processed. If multiple volumes are specified in an 
ANALYZE statement and an abnormal completion of the ANALYZE 


Operation occurs, the operation is terminated on all volumes. These values can 
be coded: 


(cuu,...) 
specifies the channel and unit address of a direct access device containing a 
volume to be initialized. This value is used only for the analysis of a volume 
offline, which includes the first analysis of a volume. If this value is coded, 
no DD statement defining a mountable device is required. When this 
volume is coded, the specified devices must be varied offline (by use of the 
VARY OFFLINE command) prior to the execution of the job step. 
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(ddname.,...) 
specifies the ddname of a job control statement defining a direct access 
device containing a volume to be analyzed, formatted, and labeled. Multiple 
ddnames specifying additional job control statements can be included. 


VTOC= xxxxx 
specifies a one- to five-byte decimal relative track address representing a 
primary track on which the volume table of contents is to begin. The VTOC 
cannot occupy track 0. 


EXTENT= xxxxx 
specifies the decimal length of the VTOC in tracks. The VTOC cannot extend 
into the alternate track area or onto a second volume. 


NEWVOLID=S serial 
specifies a One- to six-character serial number. The serial number is assigned 
to all direct access volumes processed through the use of this control 
statement. If NEWVOLID is omitted, all direct access volumes retain their 
own serial numbers. This parameter is required for the analysis of a volume 
offline. 


IPLDD= ddname 
specifies the ddname of a DD statement defining the data set containing the 
IPL program. The IPL program can be included in the SYSIN (input stream) 
data set, or it can be defined as a sequential data set or a member of a 
partitioned data set. If IPL text is included in the input stream, an IPLTXT 
statement is used to separate the ANALYZE statement from the IPL program 
text statements. Maximum IPL record size is restricted to 3,625 bytes. IPLDD 
applies to 2305, 2314, 2319, and 3330 volumes. 


FLAGTEST= 
specifies whether a check is to be made for previously flagged tracks. When a 
volume is initialized offline, no check is made. These values can be coded: 


YES 
specifies that each track is to be checked to see if it was previously flagged 
as defective. If FLAGTEST is omitted, YES is assumed. 


NO 
specifies that the program is not to check for previously flagged tracks on 
the volume. 


PASSES= 
specifies the number of passes to be made in analyzing a recording surface. 
These values can be coded: 


n 
specifies the number of times a bit pattern test is to be performed. The n 
value is a decimal number from 1 to 255. If PASSES is omitted, the bit 
pattern test is performed once on each track. 


specifies that the ANALYZE function is to bypass all surface analysis and 
track formatting, writing only a VTOC, track zero records (IPL bootstrap 
and volume label records), and IPL text if requested. The 0 value applies to 
all direct access volumes supported by IEHDASDR. If the device is a 3330, 
only the 0 specification is allowed, and is forced regardless of the PASSES 
parameter. This value is applicable to all previously initialized direct access 
devices supported by IEHDASDR while online. The offline ‘quick DASDI” 
feature is supported for all direct access devices. 
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OWNERID= name 
specifies a one- to ten-character name or other identifying information to be 
placed in the volume label record. OWNERID is specified as an EBCDIC 
character string with the exclusion of the blank and the comma characters 
(these terminate the control card scan of a field or an entire card). J 


PURGE= 
specifies whether the ANALYZE operation is to be terminated when an 
unexpired data set is encountered. If PURGE is omitted, and an unexpired 
data set is encountered, the ANALYZE operation is terminated. These values 
can be coded: 


YES 
indicates that all unexpired data sets on the volume can be overwritten 
provided that the operator signals his concurrence when the first unexpired 
data set is encountered. 


NO 
specifies that the ANALYZE operation is to be terminated if an unexpired 
data set is encountered. 


If PURGE=YES is coded and an unexpired data set is encountered, the operator 
is prompted. The operator replies are: 


¢ U, which indicates that all unexpired data sets on this volume can be 
overwritten. (The ANALYZE operation continues.) 


e T, which indicates that this volume contains unexpired data sets that must not 
be overwritten. (The ANALYZE operation is terminated.) 


The PURGE parameter does not apply to password-protected data sets; that is, 
the operator must always respond with the proper password for each 
password-protected data set encountered. If he is unable to do so, the 
ANALYZE operation is terminated. Jo 


Note: If the device is online and a volume label and VTOC are present, they are 
read, and the information contained in them is used to initialize the volume. If 
the device is offline, the volume label and VTOC are ignored. 


The FORMAT statement is used to prepare a volume for operating-system use. 
Except for flag testing, no analysis is made prior to formatting a track. Previously 
flagged disk tracks remain flagged; alternate tracks are assigned, where 
applicable. Because the FORMAT statement does not cause recording-surface 
analysis, it should not be used for the first initialization of a volume. 


The output includes a list of defective tracks and their assigned alternates. 


Note: If a command reject is detected while a FORMAT operation is performed 
on an assigned alternate track on an IBM 2305 Fixed Head Storage volume, 
processing continues as if no alternate track existed. No action need be taken if 
message IEH4001 is typed out on the operator’s console in response to this 
condition. 


If FORMAT cannot read a home address, it flags the track as being defective 
and assigns an alternate track. 


The format of the FORMAT statement is: 


[label] FORMAT TODD=(ddname.,...) 
As 8? Mase VTOC= xxxxx 
[NEWVOLID= seria! ] 
| (IPLDD= ddname | 
[OWNERID= name ] 
[PURGE= {YES}] 


where: 


TODD=( ddname.,...) 
specifies the ddname of a job control statement defining a direct access device 
containing a volume to be formatted. Multiple ddnames specifying additional 
job control statements can be included. If multiple volumes are specified in a 
FORMAT statement and an abnormal completion of the FORMAT operation 
occurs, the operation is terminated on all volumes. 


VTOC= xxxxx 
specifies a one- to five-byte decimal, relative track address representing a 
primary track on which the volume table of contents (VTOC) is to reside. The 
VTOC cannot occupy track 0. 


EXTENT= xxxxx 
specifies the decimal length of the WTOC in tracks. The VTOC cannot extend 
into the alternate track area or to a second volume. 


NEWVOLID= serial 
specifies a one- to six-character serial number. The serial number is assigned 
to all direct access volumes processed through the use of this control 
statement. If NEWVOLID is omitted, the direct access volumes retain their 
own serial numbers. 


IPLDD= ddname 
specifies the ddname of a DD statement defining the data set containing the 
IPL program. The IPL program can be included in the SYSIN (input stream) 
data set, or it can be defined as a sequential data set or a member of a 
partitioned data set. If IPL text is included in the input stream, an IPLTXT 
statement is used to separate the FORMAT statement from the program text 
statements. Maximum IPL record size is restricted to 3,625 bytes. This 
parameter applies to 2305, 2314, 2319, and 3330 volumes. 


OWNERID= name 
specifies a one- to ten-character name or other identifying information to be 
placed in the volume label record. OWNERID is specified as an EBCDIC 
character string with the exclusion of the blank and the comma characters 
(these terminate the control card scan of a field or an entire card). 


PURGE= 
specifies whether the FORMAT operation is to be terminated when an 
unexpired data set is encountered. If PURGE is omitted and an unexpired data 
set is encountered, the FORMAT operation is terminated. These values can be 
coded: 


YES 
indicates that all unexpired data sets on the volume can be overwritten 
provided that the operator signals his concurrence when the first unexpired 
data set is encountered. 
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NO 
specifies that the FORMAT operation is to be terminated when an 
unexpired data set is encountered. 


If PURGE=YES is coded and an unexpired data set is encountered, the operator ' 
is prompted. The operator replies are: ) 


e U, which indicates that all unexpired data sets on this volume can be 
overwritten.(The FORMAT operation continues.) 


¢ T, which indicates that this volume contains unexpired data sets that must not 
beoverwritten. (The FORMAT operation is terminated.) 


The PURGE parameter does not apply to password-protected data sets; that is, 
the operator must always respond with the proper password for each 
password-protected data set encountered. If he is unable to do so, the FORMAT 
operation is terminated. 


LABEL Statement 


The LABEL statement is used to change the serial number of a direct access 
volume and, optionally, to update the owner field in record 3 of track 0. One 
LABEL statement must be included for each volume that is to have its label 
changed. 


The format of the LABEL statement is: 


TODD= E 
specifies the volume to be processed. These values can be coded: 


cuUu 
specifies the channel and unit address of a direct access device containing a 
volume whose serial number is to be changed. This value is used only for 
labeling an offline volume. If this value is coded, no DD statement defining 
a mountable device is required. When this value is coded, the specified 
device must be varied off line (by use of the VARY OFFLINE command) 
prior to the execution of the job step. 


ddname 
specifies the ddname of a job control statement defining a direct access 
device containing a volume whose serial number is to be changed. 


NEWVOLID= serial 
specifies a One- to six-character serial number. The serial number is assigned 
to the direct access volume processed through the use of this control 
statement. 


OWNERID= name 
specifies a one- to ten-character name or other identifying information. If 
OWNERID is omitted, the old owner information, if any, is retained. 
OWNERID is specified as an EBCDIC character string with the exclusion of 
f the blank, the dash, and the comma characters (these terminate the control 
card scan of a field or an entire card). 
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GETALT Statement 


DUMP Statement 


The GETALT statement is used to assign an alternate track for a specified disk 
track if the volume was previously initialized. 


Flags set by GETALT statement, for defective 3330 tracks, cannot be removed 
by IEHDASDR. 


The format of the GETALT statement is: 


where: 


TODD= ddname 
specifies the ddname of a job control statement defining a disk device 
containing a volume on which an alternate track is to be assigned. 


TRACK= cccchhhh 
specifies in hexadecimal the cylinder number, cccc , and head number, Ahhh, 
of a track for which an alternate track is requested. TRACK cannot specify 
track QO or the first track occupied by the VTOC. 


The DUMP statement dumps a single track, a group of consecutive tracks, or an 
entire direct access volume to one or more direct access volumes of the same ra 
device type, to one or more tape volumes, or to a system output device (printer 
assumed). When more than one file is being dumped to the same tape, the tape 

will be rewound to the load point at the end of each dump operation. 


A detailed description of the tape volume format is available in OS/VS_ Utilities 
Logic, SY35-0005. 


The format of the DUMP statement is: 


where: 


FROMDD= ddname 
specifies the ddname of the DD statement defining the device containing the 
direct access volume from which a copy or copies are to be made. 
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TODD=(ddname.,...) 
specifies the ddname of the system output device (SYSPRINT) or specifies the 
ddnames of the DD statements defining the devices containing the direct 
access or tape volumes on which copies are to be made. If 
TODD=SYSPRINT is coded, the direct access volume described by 
FROMDD is dumped to the system output device. If a permanent data check 2 
or missing address marker is encountered while reading the direct access 
volume, the defective records are identified and printed. The output may 
exceed the expected data size due to a data check in the count field of the 
error record. When dumping from a 2305 or 3330 to SYSPRINT, the SPACE 
parameter may be necessary on the SYSPRINT DD card. Allocate sufficient 
space, for example, ““CYL,(5,5)’’, to allow large capacity devices to dump to 
SYSPRINT. 


CPYVOLID= 
specifies whether receiving direct access volumes are to be assigned the serial 
number of the dumped volume. If CPYVOLID is omitted, receiving volumes 
keep their own serial numbers. These values can be coded: 


YES 
specifies that all receiving direct access volumes are to be assigned the serial 
number of the dumped volume. 


NO 
specifies that receiving volumes are to keep their own serial numbers. 


BEGIN= cccchhhh 
specifies in hexadecimal a cylinder number, cccc and head number, Ahhh, 
that identify the first track to be dumped. If BEGIN is omitted, the dump 
operation begins with track 0. 


END= cccchhhh 
specifies in hexadecimal a cylinder number, cccc , and head number, hhhh, 4 
that identify the last track to be dumped. If only one track is to be dumped, » 
both BEGIN and END specify that track address. If END is omitted, the last 
primary track of the volume is the last track to be copied. (Alternate tracks 
are not dumped unless they are assigned as alternates. ) 


PURGE= 
specifies whether the dump operation is to be terminated when an unexpired 
data set is encountered. If PURGE is omitted, the dump operation is 
terminated when an unexpired data set is encountered. PURGE does not apply 
when dumping to a restore tape. These values can be coded: 


YES 
indicates that all unexpired data sets on a receiving direct access volume 
can be overwitten, provided that the operator signals his concurrence when 
the first unexpired data set is encountered. 


NO 
specifies that the dump operation is to be terminated when an unexpired 
data set is encountered. 


If PURGE=YES is coded and an unexpired data set is encountered, the operator 
is prompted. The operator replies are: 


e U, which indicates that all unexpired data sets on the receiving direct access 
volume can be overwritten. (The DUMP operation continues.) 


e T, which indicates that the receiving direct access volume contains unexpired 
datasets that must not be overwritten. (The DUMP operation is terminated.) 
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The PURGE parameter does not apply to password-protected data sets; that is, 
the operator must always respond with the proper password for each 
password-protected data set encountered. If he is unable to do so, the dump 
Operation is terminated. 


An extra input/output error (data check) message is generated at the console 
when the dump to SYSPRINT function encounters one of the following 
conditions: 


e Missing address marker. 

¢ Data check in count and key fields and/or data field. 
e Input/output error on a search command. 

e Missing address marker and no record found. 


The additional data check message printed at the console is generated by the 
dump function’s error recovery procedure. However, the additional message is 
not reflected by a SYNADAF message in the SYSPRINT data set. If a missing 
address marker is encountered during a space count command, the function 
terminates with a return code of 8. 


Note: If multiple output volumes are specified in a DUMP statement and an 
abnormal completion of the DUMP operation occurs, the operation is terminated 
on all output volumes. 


Do not dump a volume and restore new data to that volume in the same job 
step. IEHDASDR does not flush the input stream if an operation is 
unsuccessful; that is, the program attempts to perform any remaining functions 
after encountering an error. Thus, if a dump operation is unsuccessful, data is 
lost if a subsequent restore operation places new data on the dumped volume. 


Partial dumps of direct access volumes should be used with extreme caution. 
Because only those tracks that are dumped are placed on the receiving volume, 
the partially dumped data may not be usable. When partially dumped data is 
subsequently restored, it is placed on the same tracks that it originally occupied. 


When using the DUMP statement, do not specify the same ddname in more than 
one TODD parameter in a single job step, except when the ddname is 
SYSPRINT. 


When space permits, more than one direct access volume can be dumped to a 
restore tape. However, IEHDASDR creates two files for each volume of data 
that is dumped. Therefore, the LABEL parameter sequence number in the DD 
statement defining the restore volume must be coded as 3, 5, 7, etc. for the 
second, third, fourth, etc. volume dumped to the restore tape. 


In the case of an IPL restore tape, the LABEL parameter sequence number must 
be coded as 2, 4, 6, etc. for the first, second, third, etc. volume dumped to the 
restore tape. 


The files are referred to in the same manner when restoring data to a direct 
access device. 


When processing an unlabeled tape before a dump operation, the IEHDASDR 
writes an end-of-file record (tapemark) and continues processing. 


When dumping to or restoring from a tape, specified as standard label or ‘““BLP’’, 
a disposition of KEEP should be specified in the DD statement for the tape. 
Non-labeled tapes may have other disposition parameters. 


When restoring from a restore file on a tape, the same file sequence number and 
tape label format used in the dump operation must be used. 
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Intermixing of restore files with system data sets is not recommended because of 
the unique format of the restore file. 


RESTORE Statement 


The RESTORE statement is used to restore a direct access volume or volumes 
from a tape volume on which a dumped copy was previously placed. : 


Note: When a standard-labeled restore tape created by IBCDMPRS is restored 
by IEHDASDR, the DD card describing the tape for IEHDASDR can specify 
LABEL=(2,BLP). Bypass-label-processing must have been system generated by 
specifying OPTIONS=BYLABEL on the SCHEDULR control card. If 
bypass-label-processing is not available, any standard-labeled tape created by 
IBCDMPRS can be restored by IEHDASDR, by providing appropriate DCB 
parameters on the DD statement for the tape (RECFM=U, BLKSIZE=track 
length). 


The format of the RESTORE statement is: 


WA 


where: 


TODD=( ddname.,...) 
specifies the ddnames of the DD statements defining the devices containing 
the direct access volumes to be restored. If multiple output volumes are 
specified in a RESTORE statement and an abnormal completion of the restore 
Operation occurs, the operation is terminated on all output volumes. 


FROMDD= ddname - 
specifies the ddname of the DD statement that defines the tape volume 
containing the data to be restored. If more than one tape volume is to be used 
as input, the DD statement for the tape must indicate multiple volumes. 


CPYVOLID 
specifies whether restored direct access volumes are to be assigned the serial 
number of the dumped direct access device. If CPYVOLID is omitted, 
receiving volumes keep their own serial numbers. These values can be coded: 


YES 
specifies that all restored direct access volumes are to be assigned the serial 
number of the dumped direct access volume. 


NO 
specifies that receiving volumes are to keep their own serial numbers. 


PURGE= 
specifies whether the restore operation is to be terminated when an unexpired 
data set is encountered. If PURGE is omitted, the restore operation is 
terminated when an unexpired data set is encountered. 


YES 
specifies that all unexpired data sets on the receiving direct access volume 
can be overwritten provided that the operator signals his concurrence when 
the first unexpired data set is encountered. 
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IPLTXT Statement 


PUTIPL Statement 


NO 
specifies that the restore operation is to be terminated if an unexpired data 


set 1S encountered. 


If PURGE=YES is coded and an unexpired data set is encountered, the operator 
is prompted. The operator replies are: 


e U, which indicates that all unexpired data sets on this volume can be 
overwritten. (The restore operation continues.) 


¢ T, which indicates that this volume contains unexpired data sets that must not 
be overwritten. (The restore operation is terminated.) 


The PURGE parameter does not apply to password-protected data sets; that is, 
the operator must always respond with the proper password for each 
password-protected data set encountered. If he is unable to do so, the restore 
operation is terminated. 


The IPLTXT statement is used to mark the beginning of IPL program text 
statements. The IPL text must follow the first statement referring to it. 


IPL text need be included only once in the input stream; that is, IEHDASDR 
refers to the first copy of IPL text encountered when performing multiple 
functions in a single job step. 


The format for the IPLTXT statement is: 
i Sa pa TERS. heh a. 4 tad : Se ath aye: 


a . 
a “ : 
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= Sap as yp (Fo 
a a aye” 2 
“ 
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The PUTIPL statement specifies that IPL bootstrap records and a program are to 
be read from an input data set and written to cylinder 0, track O of a direct 
access volume. As a result, cylinder 0, track 0 of the output volume will contain 
a program that the user should be able to load from the console. 

The format of the PUTIPL statement is: 


-~ ‘ 


FROMDD= ddname 
specifies the ddname of the DD statement that identifies the input data set. 
(The DD statement must contain the DSNAME and DISP parameters and, if 
the input data set is not cataloged or passed from an earlier step, the VOL 
and UNIT parameters.) 


TODD= ddname 
specifies the ddname of the DD statement that identifies the volume serial 
number of the output volume. (The UNIT parameter must specify a 2305, 
2314, or 3330 volume, and DISP must equal OLD. VOL must not specify the 
system residence volume.) The input data set must be in the form of from 
three to five variable length records. The first two records must be IPL1 and 
IPL2 type records with record lengths of exactly 24 (IPL1) and 144 (IPL2) 
bytes. The remaining one to three records must have a cumulative length not 
greater than the remaining track capacity with a 3072 byte maximum size for 
any one of the three records. 


PURGE= 
specifies whether user labels are to be overwritten. These values can be coded: 
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YES 


specifies that the program may be written over any user labels or over any 
data that follows the volume label record. 


NO 


specifies that the program may not be written over standard user labels. If 
the output device is a 2305 or 3330, the program is written following any 


standard user labels. If the output volume contains user labels and the 
output device is a 2314 or 2319, there may not be enough space on the 
track for a program; in this case, the write operation is terminated. 


The following examples illustrate some of the uses of IEHDASDR. Table 33 can 
be used as a quick reference guide to IEHDASDR examples. The numbers in the 
“Example” column point to examples that follow. 


Table 33. IEHDASDR Example Directory 


Operation 
INITIALIZE 


INITIALIZE 


GETALT 
and LABEL 
DUMP 


DUMP 


DUMP 


RESTORE 


DUMP and 
RESTORE 


RESTORE 


WRITE 
PROGRAM 


FORMAT 


FORMAT 


Quick- 
DASDI 


Device 
2314 Disk 


2314 Disks 


3330 Disk 
2314 Disks 


2305-1 Disk, 
system output 
device 


2314 Disk, 
9-track tape 


3330 Disks, 
7-track tape 


2314 Disks, 
9-track tape 


9-track tape, 
2314 Disk 


2305-2 Disk, 
2314 Disk 


3330 Disk 


3330 Disk 
3330 Disk 


Comments 


Volume ts to be initialized for the first time; 
therefore, recording surface is analyzed. IPL 
text is included in the input stream. 


Three previously initialized volumes are to 

be initialized; their volume serial numbers are 
to be changed. Surface analysis is to be 
performed at the same time. 


Get alternate tracks for a previously initialized 
volume and change its volume serial number. 


Dump a copy of one volume to three other 
volumes. 


Dump a group of tracks to the system output 
device, which is assumed to be a printer. 


Dump a disk volume to magnetic tape. Only 
one tape volume is required. 


A 3330 disk volume, previously dumped to 
tape, is to be restored to direct access. 


Dump operations are to be performed 
concurrently to minimize input/output time. 
Restore operations are to be performed 
concurrently to minimize input/output time. 


A 2314 volume, previously dumped to two tape 
volumes, is to be restored to disk. 


Write IPL bootstrap records and a program 
on track 0 of a direct access volume. 


Format a disk by writing an RO on 
each track. The IPL text is included 
in the input stream. Volume serial 
is changed. 


Format two disks. 


Uses ANALYZE function to build VTOC 
and change volume serial number. 


Example 


11 
12 


In this example, a blank 2314 volume is to be analyzed and formatted for the 
first time. Because this example deals with a blank volume, two considerations 
must be made: 


1. The TODD parameter in the ANALYZE statement must specify a channel ; 


and unit address, rather than a ddname. 


C 
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2. The selected device (in this example, unit 130) must be varied offline by the 
operator; that is, before the job is executed, the operator must use the VARY 
OFFLINE command. 


The example follows: 


72 
//DASDR1 JOB 
a EXEC PGM=IEHDASDR 
//SYSPRINT DD  SYSOUT=A 
//SYSIN DD * 
ANALYZE TODD=130,VTOC=00004, EXTENT=00010, Vc 
NEWVOLID=231400,OWNERID=SMITH, \\G 


IPLDD=SYSIN, FLAGTEST=NO 
IPLTXT 


IPL TXT (text) statements 


END 
/* 


The control statements are discussed below: 
e SYSIN DD defines the control data set, which follows in the input stream. 


e ANALYZE defines a mountable device on which a blank 2314 volume is to 
be mounted. This statement defines the starting location and extent of a 
VTOC, specifies a serial number and owner identification, indicates that no 
flag testing is to be performed, and indicates that IPL text is included in the 
input stream. 


e IPLTXT signals the start of IPL text. 
e END signals the end of IPL text. 


In this example, three previously initialized 2314 volumes are to be initialized 
and assigned new Serial numbers. 


The example follows: 


72 
//DASDR2 JOB 
ji EXEC PGM=IEHDASDR 
//SYSPRINT DD SYSOUT=A 
//4OL1 DD  UNIT=(2314,,DEFER),DISP=OLD, 
// VOLUME=( PRIVATE, ,SER=( 231400 )) 
//NOL2 DD UNIT=(2314,,DEFER),DISP=OLD, 
// OLUME=( PRIVATE, , SER=( 231401)) 
//VOL3 DD UNIT=(2314,,DEFER),DISP=OLD, 
// VOLUME=( PRIVATE, , SER=( 231402) ) 
//SYSIN DD * 
ANALYZE  TODD=VOL1, VTOC=00003, EXTENT=00010, \\e 
OWNERID=SMITH, NEWVOLID=DISKO1, FLAGTEST=NO 
ANALYZE TODD=VOL2, VTOC=00006, EXTENT=00010, VSc 
OWNERID=SMITH, NEWVOLID=DISKO02 , FLAGTEST=NO 
ANALYZE  TODD=VOL3, VTOC=00004, EXTENT=00010, mre 


OWNERID=SMITH, NEWVOLID=DISKO3 , FLAGTEST=NO 
/* 
The control statements are discussed below: 


e VOLI, VOL2, and VOL3 DD define three 2314 devices on which the 
volumes to be initialized are mounted. 


e SYSIN DD defines the control data set, which follows in the input stream. 
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¢ The ANALYZE statements indicate the ddnames of DD statements defining 
devices on which the three 2314 volumes (231400, 231401, and 231402) are 
to be mounted. The ANALYZE statements also define starting locations and 
extents of the three VTOCs, specify new owner names and serial numbers 
(DISKO1, DISKO2, and DISKO3), and indicate that no flag testing is to be 
performed on these volumes. 
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In this example, alternate tracks are to be assigned for three suspected defective 
tracks on a 3330 volume. 


The example follows: 


//DASDR3 JOB 
EXEC PGM=IEHDASDR 
//SYSPRINT DD  SYSOUT=A 
//JOLUME1 DD  UNIT=(3330,,DEFER),DISP=OLD, 
// VOLUME=( PRIVATE, ,SER=( 333000)) 
//SYSIN DD * 
GETALT TODD=VOLUME1, TRACK=00050011 
GETALT TODD=VOLUME1, TRACK=O00A00007 
GETALT TODD=VOLUME1,TRACK=01010002 
LABEL TODD=VOLUME1,NEWVOLID=DISKOO,OWNERID=SMITH 
/* 


The control statements are discussed below: 


e VOLUME! DD defines a device that is to contain the 3330 volume (333000). 


e SYSIN DD defines the control data set, which follows in the input stream. 


e The GETALT statements specify the ddname of the DD statement defining 
the device on which the 3330 volume is mounted. The GETALT statements 
specify the relative track addresses of the tracks for which alternates are to be 
assigned. 


e LABEL specifies the ddname of the DD statement defining the device on 
which the 3330 volume is mounted. The LABEL statement changes the serial 
number of the 3330 volume from 333000 to DISKOO. 
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In this example, a copy of an entire volume (231400) is to be dumped to three 
volumes (231401, 231402, and 231403). 


The example follows: 


//DASDR4 JOB 

// EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 

//DUMPFROM DD  UNIT=(2314,,DEFER),DISP=OLD, 
// \JIOLUME=( PRIVATE, , SER=( 231400) ) 

//DUMPTO1 DD  UNIT=(2314,,DEFER),DISP=OLD, 
// \NOLUME=( PRIVATE, , SER=( 231401) ) 

//DUMPTO2 DD  UNIT=(2314,,DEFER),DISP=OLD, 
// VOLUME=( PRIVATE, , SER=( 231402) ) 

//DUMPTO3 DD  UNIT=(2314,,DEFER),DISP=OLD, 
// \IOLUME=( PRIVATE, , SER=( 231403) ) 

//SYSIN DD * 

DUMP | FROMDD=DUMPFROM, TODD=( DUMPTO1, DUMPTO2, DUMPTO3 ), PURGE=YES 
/* 


The control statements are discussed below: 


e DUMPFROM DD defines a mountable device that is to contain a source 
volume. 


J 


C 


C 
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¢ DUMPTOI1, DUMPTO2, and DUMPTO3 DD define mountable devices that 
are to contain the three receiving volumes. 


e DUMP specifies the dump operation and identifies the DD statements defining 
the applicable devices. All receiving volumes are to retain their own serial 
numbers. 


In this example, a copy of tracks 0 through 60 is to be dumped from a disk 
volume (230500) to a system output device. 


The example follows: 


//DASDR5 JOB 
EXEC PGM=ITEHDASDR 
//SYSPRINT DD SYSOUT=A 


/ /DEV DD  UNIT=2305-1,DISP=OLD, 
// VOLUME=( PRIVATE, , SER=( 230500 )) 
//SYSIN DD * 


DUMP FROMDD=DEV , TODD=SYSPRINT, BEGIN=Q0000000 , END=00070004 
/* 


The control statements are discussed below: 
e DEV DD defines a device that is to contain the source volume. 


e DUMP specifies the dump operation, identifies the DD statements defining the 
source and receiving devices, and identifies the tracks that are to printed. 


In this example, a 2314 volume (231400) is to be dumped to a 9-track, 800 bits 
per inch, tape volume (240000). 


The example follows: 


//DASDR6 JOB 
EXEC PGM=IEHDASDR 

//SYSPRINT DD  SYSOUT=A 
//SOURCE DD  UNIT=(2314,,DEFER),DISP=OLD, 
// VOLUME=( PRIVATE, , SER=( 231400) ) 
//RECEIVE DD  UNIT=(2400,,DEFER),DISP=NEW, DSNAME=TAPE1, 
// VOLUME=( PRIVATE, , SER=( 240000 ) ) 
//SYSIN DD * 

DUMP FROMDD=SOURCE, TODD=RECEIVE 


/* 
Note: This example assumes that only one tape volume is required. If more than 
One is required, code the volume serial numbers of the additional volumes in the 
VOLUME parameter of the DD statement that defines the magnetic tape device. 
For unlabeled tapes, include a volume count in the DD statement. 


The control statements are discussed below: 


e SOURCE DD defines a mountable device that is to contain the source 
volume. 


« RECEIVE DD defines a 9-track tape drive that is to contain the receiving 
tape volume. 


« DUMP specifies the dump operation and identifies the DD statements defining 
the source and receiving devices. 


In this example, three disk volumes (333000, 333001, and 333002) are to be 
restored from a 7-track, 556 bits per inch, standard-labeled tape volume. 
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The example follows: 


/ /DASDR7 JOB 


pf EXEC PGM=IEHDASDR 

JP OVSPR ENE DD SYSOUT=A 

//TAPE DD UNIT=( 2400-2, ,DEFER),DISP=OLD, 
// DCB=( TRTCH=C,DEN=1 ),DSNAME=TAPE1, 


// VOLUME=( PRIVATE, ,SER=( 240000) ) 
//DIRACC1 DD  UNIT=(3330,,DEFER),DISP=OLD, 
// OLUME=( PRIVATE, ,SER=( 333000 ) ) 
//DIRACC2 DD  UNIT=(3330,,DEFER),DISP=OLD, 
// VOLUME=( PRIVATE, , SER=( 333001 ) ) 
//DIRACC3 DD  UNIT=(3330,,DEFER),DISP=OLD, 
// VIOLUME=( PRIVATE, , SER=( 333002 ) ) 
//SYSIN DD * 
RESTORE  TODD=(DIRACC1,DIRACC2,DIRACC3 ),FROMDD=TAPE 
/¥* 


The control statements are discussed below: 


¢ TAPE DD defines a 7-track tape unit that is to contain the source tape 
volume. 


¢ DIRACC1, DIRACC2, and DIRACC3 DD define mountable devices that are 
to contain the three receiving volumes. 


e RESTORE specifies the restore operation and identifies the DD statements 
defining the source and receiving devices. The receiving volumes retain their 
own serial numbers. 


In this example, two direct access volumes are to be dumped concurrently to two 
receiving volumes in one operation; two direct access volumes are to be restored 
concurrently from two 9-track, 800 bits per inch, standard-labeled tape volumes 

in another operation. 


The example follows: 


//DASDR8 JOB 

Pay EXEC PGM=IEHDASDR 

//SYSPRINT DD  SYSOUT=A 

//SOURCE1 DD  UNIT=(2314,,DEFER),DISP=OLD, 

// VOLUME=( PRIVATE, , SER=( 231400) ) 

//SOURCE2 DD  UNIT=(2314,,DEFER),DISP=OLD, 

// VOLUME=( PRIVATE, , SER=( 231401) ) 

LITO) DD UNIT=2314, VOLUME=SER=231402,DISP=OLD 
T/TOD DD UNIT=2314, VOLUME=SER=231403,DISP=OLD 
//SOURCE3 DD  UNIT=(2400,,DEFER),DISP=OLD,LABEL=( ,NL), 
// VOLUME=( PRIVATE, ,SER=( 240000 ) ) 

//SOURCE4 DD  UNIT=( 2400, ,DEFER),DISP=OLD,LABEL=(,NL), 
// VIOLUME=( PRIVATE, , SER=( 240001) ) 


//TO3 DD UNIT=AFF=TO1,VOLUME=SER=231404,DISP=OLD 
//TO4 DD UNIT=AFF=TO2,VOLUME=SER=231405,DISP=OLD 
//SYSIN DD * 


DUMP FROMDD=SOURCE1 , TODD=TO1 
DUMP FROMDD=SOURCE2 , TODD=TO2 
RESTORE TODD=TO3 , FROMDD=SOURCE3 
RES FORE TODD=TO4 , FROMDD=SOURCE4 


/* 
The control statements are discussed below: 


¢« SOURCEI1 and SOURCE2 DD define devices on which the source volumes 
for the dump operation are to be mounted. 


e TO1 and TO2 DD define devices on which the receiving volumes for the 
dump operation are to be mounted. 


C 


IEHDASDR Example 9 


IEHDASDR Example 10 


e SOURCE3 and SOURCE4 DD define devices on which the source tape 
volumes for the restore operation are to be mounted. 


e TO3 and TO4 DD define devices on which the receiving direct access volumes 
for the restore operation are to be mounted. The receiving volumes for the 
restore Operation are to be mounted on the same devices as the receiving 
volumes for the dump operation were mounted. 


In this example, a 2314 volume previously dumped to tape is to be restored. 
Because a completely filled 2314 volume requires more space than is available on 
a single reel of 9-track, 800 bits per inch tape, two tape volumes were used in 
the dump operation. 


The example follows: 


/ /DASDRY JOB. (0O#990;,SMITH 


74, EXEC PGM=IEHDASDR 

/7/SYSPRINT- DD SYSOUT=A 

//TAPE DD UNI T=2400, VOL=(,,,2,SER=240000, 2400001 ), 
// DISP=OLD 

JL OTSEK DD UNI T=2314,VOL=SER=231400,DISP=OLD 

Fi SLSIN DD * 


RESTORE FROMDD=TAPE, TODD=DISK 
/* 


The control statements are discussed below: 


« TAPE DD defines the 9-track tape volumes that contain the data to be 
restored to disk. 


e DISK DD defines the 2314 volume to which data is to be restored. 


« RESTORE specifies that data is to be restored from the tape volumes defined 
in the TAPE DD statement to the 2314 volume defined in the DISK DD 
statement. 


Note: For nonlabeled tapes, use the external volume identification and the 
LABEL=(,NL) parameter on the associated tape DD card. 


In this example, IPL bootstrap records and a program are to be written on track 
0 of a direct access volume. 


The example follows: 


Jf7/ DBSDR 10. JOB 


Vas EXEC PGM=IEHDASDR 
J//SYSPRINY ‘DD SYSOUT=A 
//INPUT DD DSNAME=IPLPROG, UNIT=2305-2, 


// VOL=SER=230502,DISP=OLD 
/ f/OUTPUT DD UNIT=2314, VOL=SER=231401,DISP=OLD 
7 /SLSIN DD * 

PUTIPE FROMDD=INPUT, TODD=OUTPUT , PURGE=YES 
/* 


The control statements are discussed below: 


e INPUT DD defines the input data set, which contains the IPL records and 
program to be written. The input data set resides on a 2305 volume. 


« OUTPUT DD defines the output data set, which is to reside on a 2314 
volume. 


e SYSIN DD defines the control data set, which follows in the input stream. 
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e PUTIPL identifies the DD statements (INPUT and OUTPUT) that define the 
input and output data sets and specifies that the program to be written on the 
2314 volume can be written over any data after the volume label record. 


Note that the 2319 is functionally equivalent to the 2314; to use a 2319 volume, 


specify 2314. ) 


In this example, a 3330 volume is formatted and assigned a new serial number. 


The example follows: 


2 
//DASDR11 JOB 
// EXEC PGM=IEHDASDR 
//SYSPRINT DD SYSOUT=A 
//DISK DD UNIT=3330,DISP=OLD, VOL=( PRIVATE, , SER=( 333000) ) 
//SYSIN DD # 
FORMAT TODD=DISK, VTOC=00006 , EXTENT=00005, VSc 


NEWVOLID=333001,PURGE=YES, IPLDD=SYSIN 
IPLTAT 


er VED se REE) 


END 


/* 
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The control statements are discussed below: 
« DISK DD defines the 3330 device on which the volume (333000) is mounted. 
e SYSIN DD defines the control data set which follows in the input stream. 


e FORMAT defines a starting location and extent of a volume table of contents, 
specifies a new serial number, and indicates that the IPL text is included in the } 
input stream. Record O of each track is rewritten. 


e IPLTXT signals the start of IPL text. 
e END signals the end of IPL text. 


In this example, two 3330 volumes are formatted. 
The example follows: 


//DASDR12. JOB 
EXEC PGM=IEHDASDR 

//SYSPRINT DD SYSOUT=A 
//DISKO1 DD UNIT=3330,DISP=OLD,VOL=( PRIVATE, , SER=( 333001 ) ) 
//DISKO2 DD UNIT=3330,DISP=OLD, VOL=( PRIVATE, , SER=( 333002) ) 
//SYSIN DD * 

FORMAT TODD=(DISKO1,DISKO2 ),VTOC=00010, EXTENT=00010 
/* 


The control statements are discussed below: 


¢ DISKO1 and DISKO2 DD define the 3330 devices on which the volumes 
(333001 and 333002) are mounted. 


e FORMAT defines a starting location and extent of a volumes table of 
contents. The RO of each track is rewritten. 


In this example a 3330 volume is initialized with a VTOC and volume serial P 
number—or ‘“‘quick-DASDI.”’ 4 


The example follows: 


//DASDR13 JOB 
EXEC PGM=ITEHDASDR 
//SYSPRINT DD SYSOUT=A 
PADISK DD UNIT=3330,DISP=OLD, VOL=( PRIVATE, ,SER=( 333000) ) 
F7SLSLN DD. 
ANALYZE TODD=DISK,VTOC=00005, EXTENT=00010, NEWVOLID=333333 


/* 
The control statements are discussed below: 
« DISK DD defines the 3330 device on which the volume (333000) is mounted. 


e ANALYZE defines the starting location and extent of the volume table of 
contents.For 3330 devices, PASSES=0 is the default so that only a 
‘““quick-DASDI”’ is performed. 
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IEHINITT Program 


IEHINITT is a system utility used to place IBM volume label sets written in 
EBCDIC, in BCD, or in ASCII (American Standard Code for Information 
Interchange) on magnetic tapes mounted on one or more tape units. (See 
“Introduction” for general system utility information.) Each volume label set 
created by the program contains: 


e A standard volume label with user specified serial number and owner 
identification. 

e An 80-byte dummy header label. For IBM standard labels, this record consists 
of HDR1 followed by zeros. For ANS labels, this record consists of HDR1 


followed by zeros in the remaining positions, with the exception of position 
54, which contains an ASCII space. 


e A tapemark. 


Note: When a labeled tape is subsequently used as a receiving volume: (1) the 
tape mark created by IEHINITT is overwritten, (2) the dummy HDR1 record 
created by IEHINITT is filled in with operating system data and 
device-dependent information, (3) a HDR2 record, containing data set 
characteristics, is created, (4) user header labels are written if exits to user label 
routines are provided, (5) a tapemark is written, and (6) data is placed on the 
receiving volume. 


Figure 46 shows an IBM standard label group after a volume is used to receive 
data. Refer to OS/VS Data Management Services Guide, GC26-3783, for a 
discussion of volume labels. 


Initial volume label 
HDR1 


HDR2 


User header labels 
(optional up to 8) 


Figure 46. IBM Standard Label Group After Volume Receives Data 


Placing a Standard Label Set on Magnetic Tape 


IEHINITT can be used to write BCD labels on 7-track tape volumes and 
EBCDIC or ASCII labels on 9-track tape volumes. Any number of 7-track 
and/or 9-track tape volumes can be labeled in a single execution of IEHINITT. 


Tape volumes are labeled in sequential order by specifying a serial number to be 
written on the first tape volume. The serial number is incremented by 1 for each 
successive tape volume. If only one tape volume is to be labeled, the specified 
serial number can be either numeric or alphameric. If more than one volume is to 
be labeled, the serial numbers must be specified as six numeric characters. 
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The user can provide additional information, such as owner name, rewind or 
unload specifications, and whether the label is to be written in ASCII. 


The user must supply all tapes to be labeled, and must include with each job 
request explicit instructions to the operator about where each tape is to be 


mounted. | > 


If any errors are encountered while attempting to label a tape, the tape is left 
unlabeled. IEHINITT attempts to label any tapes remaining to be processed. 


For information on creating routines to write standard or non-standard labels, 
refer to OS/VS Tape Labels, GC26-3795. 


IEHINITT writes 7-track tape labels in even parity (translator on, converter off). 


Previously labeled tapes can be overwritten with new labels regardless of 
expiration date and security protection. 


Input and Output 


IEHINITT uses as input a control data set that contains the utility control 
statements. 


IEHINITT produces an output data set that contains: (1) utility program 
identification, (2) initial volume label information for each successfully labeled 
tape volume, (3) contents of utility control statements, and (4) any error 
messages. 


IEHINITT produces a return code to indicate the results of program execution. 
The return codes and their meanings are: 


¢ 00, which indicates successful completion. A message data set was created. 


¢ 04, which indicates successful completion. No message data set was defined by 


the user. ) 


¢ 08, which indicates that the program completed its operation, but error 
conditions were encountered during processing. A message data set was 
created. 


¢ 12, which indicates that the program completed its operation, but error 
conditions were encountered during processing. No message data set was 
defined by the user. 


e 16, which indicates that the program terminated operation because of error 
conditions encountered while attempting to read the control data set. A 
message data set was created if defined by the user. 


Control 


IEHINITT is controlled by job control statements and utility control statements. 
The job control statements are used to execute or invoke IEHINITT and to 
define data sets used and produced by IEHINITT. Utility control statements are 
used to specify applicable label information. 


Job Control Statements 
Table 34 shows the job control statements necessary for using IEHINITT. 
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Restrictions 


L 


Table 34. IEHINITT Job Control Statements 


Statement Use 
JOB Initiates the job. 
EXEC Specifies the program name (PGM=IEHINITT) or, if the job control 


statements reside in a procedure library, the procedure name. The EXEC 
statement can include additional PARM information; see ““PARM 
Information on the EXEC Statement.” 


SYSPRINT DD _ Defines a sequential output data set. 


anyname DD Defines a tape unit to be used in a labeling operation; more than one tape 
unit can be identified. 


SYSIN DD Defines the control data set. The control data set normally resides in the 
input stream; however, it can be defined as a member of a partitioned data 
set or as a sequential data set outside the input stream. 


The “‘anyname” DD statement is entered: 
//anyname DD DCB=DEN=x,UNIT=(xxxx,n, DEFER) 


The DEN parameter specifies the density at which the labels are written. The 
UNIT parameter specifies the device type, number of units to be used for the 
labeling operation, and deferred mounting. The name ‘‘anyname”’ must be 
identical to a name specified in a utility control statement to relate the specified 
unit(s) to the appropriate utility control statement. 


e The SYSPRINT data set must have a logical record length of 121 bytes. It 
must consist of fixed length records with an ASA control character in the first 
byte of each record. Any blocking factor can be specified. 


e The SYSIN data set must have a logical record length of 80. Any blocking 
factor can be specified. 


e ANS labels cannot be put on 7-track tape volumes. 


PARM Information on the EXEC Statement 


The EXEC statement can include PARM information that specifies the number 
of lines to be printed between headings in the message data set, as follows: 


PARM=LINECNT=nn 
If PARM is omitted, 60 lines are printed between headings. 


If IEHINITT is invoked, the line count option can be passed in a parameter list 
that is referred to by the “‘optionaddr” subparameter of the LINK or ATTACH 
macro instruction. In addition, a page count can be passed in a six-byte 
parameter list that is referred to by the “‘hdingaddr’’ subparameter of the LINK 
or ATTACH macro instruction. For a discussion of linkage conventions, refer to 
‘Appendix B: Invoking Utility Programs from a Problem Program.” 


Utility Control Statement 


INITT Statement 


IEHINITT uses a utility control statement to provide control information for a 
labeling operation. 


The INITT statement provides control information for the IEHINITT program. 


Any number of INITT utility control statements can be included for a given 
execution of the program. An identically named DD statement must exist for a 
utility control statement in the job step. 
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The format of the INITT statement is: 
name INITT SER= xxxxxx 
~ [OWNERS ccecccecece [ cccc }’| 
[NUMBTAPE= n ] ) ) 


a  BISP= fREWIND} 
: { UNLOAD} 
(LABTYPE=AL] 
where: 
name 


specifies a name that is identical to a ddname in the name field of a DD 
statement defining a tape unit(s). This name must begin in column 1. 


SER= xxxxxx 
specifies the volume serial number of the first or only tape to be labeled. The 
serial number cannot contain blanks, commas, apostrophes, equal signs, or 
special characters other than periods or hyphens. A specified serial number is 
incremented by one for each additional tape to be labeled. (Serial number 
999999 is incremented to OO0000.) When processing multiple tapes, the 
volume serial number must be all numeric. 


OWNER=S‘ cccccccccc [ cccc |’ 
specifies the owner’s name or similar identification. The information is 
specified as character constants, and can be up to 10 bytes in length for 
EBCDIC and BCD volume labels, or up to 14 bytes in length for ANS 
volume labels. The delimiting apostrophes can be omitted if no blanks, 
commas, apostrophes, equal signs, or other special characters (except periods 
or hyphens) are included. If an apostrophe is included, it must be written as 
two consecutive apostrophes. 


NUMBTAPE= n : 


specifies the number of tapes to be labeled according to the specifications 
made in this control statement. The value n represents a number from 1 to 
255. If NUMBTAPE is omitted, one tape volume is labeled. If more than one 
tape is specified, the serial number must be numeric. 


DISP= 
specifies whether a tape is to be rewound or unloaded. These values can be 
coded: 


REWIND 
specifies that a tape is to be rewound (but not unloaded) after the label has 
been written. If DISP=REWIND is not specified, the tape volume is 
rewound and unloaded. 


UNLOAD 
specifies that a tape is to be unloaded after the label has been written. 


LABTYPE=AL 
specifies that an ANS volume label is to be created. If LABTYPE is not 
specified, the tape is written in EBCDIC for 9-track tape volumes and in BCD 
for 7-track tape volumes. 


Figure 47 shows a printout of a message data set including the INITT statement 
and initial volume label information. In this example, one INITT statement was 
used to place serial numbers 001122 and 001123 on two tape volumes. 
VOL10011220 and VOL10011230 are interpreted, as follows: 


e VOLI indicates that an initial volume label was successfully written to a tape ‘ 
volume. - 


L 
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IEHINITT Example 1 


IEHINITT Example 2 


e 001122 and 001123 are the serial numbers that were written onto the 
volumes. 


e Q is the Volume Security field. 


No errors occurred during processing. 


72 
oY o TEM SUPPORT -UTLLITLES TERI NTP 
ALL INITT SER=001122,NUMBTAPE=2,OWNER='P.T.BROWN', \ Vc 
DISP=REWIND 
VOL10011220 P.T.BROWN 
VOL10011230 P.T.BROWN 
Figure 47. Printout of INITT Statement Specifications and Initial Volume Label 
Information 


The following examples illustrate some of the uses of IEHINITT. Table 35 can 
be used as a quick reference guide to IEHINITT examples. The numbers in the 
‘‘Example” column point to examples that follow. 


Table 35. IEHINITT Example Directory 


Operation Comments Example 
LABEL Three 9-track tapes are to be labeled. 1 
LABEL A 9-track tape is to be labeled. 2 
LABEL Two groups of 9-track tape volumes are to be labeled. 3 
LABEL 9-track tape volumes are to be labeled. Sequence 
numbers are to be incremented by 10. 4 
LABEL Three 9-track tape volumes are to be labeled. An 
alphameric label is to be placed on a 2400 volume; 
numeric labels are placed on the 2400-4 volumes. 5 


In this example, serial numbers 001234, 001235, and 001236 are to be placed on 
three tape volumes; the labels are to be written in EBCDIC at 800 bits per inch. 
Each volume to be labeled is mounted, when it is required, on a single 9-track 
tape unit. 


The example follows: 


//UABEL1 JOB 09#990, BROWN ,MSGLEVEL=(1,1 ) 


df EXEC PGM=IEHINITT 

//SYSPRINT DD  SYSOUT=A 

//LABEL DD DCB=DEN=2,UNIT=( 2400,1,DEFER) 
//SYSIN DD * 

LABEL INITT  SER=001234,NUMBTAPE=3 

/* 


In this example, serial number 001001 is to be placed on one ASCII tape 
volume; the label is to be written at 800 bits per inch. The volume to be labeled 
is mounted, when it is required, on a 9-track tape unit. 
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IEHINITT Example 3 


IEHINITT Example 4 


IEHINITT Example 5 
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The example follows: 


//UABEL2 JOB 0O9#990,BROWN,MSGLEVEL=( 1,1 ) 
EXEC PGM=IEHINITT 
//SYSPRINT DD SYSOUT=A 
//ASCIILAB DD DCB=DEN=2,UNIT=( 2400, 1,DEFER ) 
f{SLSIN DD m= 
ASCIILAB INITT SER=001001,OWNER='SAM A. BROWN' , LABTYPE=AL 
/* 


In this example, two groups of serial numbers (001234, 001235, 001236, and 
001334, 001335, 001336) are placed on six tape volumes. The labels are to be 
written in EBCDIC at 800 bits per inch. Each volume to be labeled is mounted, 
when it is required, on a single 9-track tape unit. 


The example follows: 


//LABEL3 JOB 09#990,BROWN,MSGLEVEL=( 1,1 ) 


// EXEC PGM=IEHINITT 

//SYSPRINT DD SYSOUT=A 

//LABEL DD DCB=DEN=2,UNIT=(2400,1,DEFER) 
//SYSIN DD * 

LABEL INITT  SER=001234,NUMBTAPE=3 

LABEL INITT  SER=001334,NUMBTAPE=3 

/* 


In this example, serial numbers 001234, 001244, 001254, 001264, 001274, etc., 
are to be placed on eight tape volumes. The labels are to be written in EBCDIC 
at 800 bits per inch. Each volume to be labeled is mounted, when it is required, 
on one of four 9-track tape units. 


The example follows: 


/ / LABEL4 JOB 09#990,BROWN,MSGLEVEL=( 1,1 ) 


Tf, EXEC PGM=IEHINITT 
//SYSPRINT DD SYSOUT=A 
//LABEL DD  DCB=DEN=2,UNIT=(2400,4,DEFER) 
//SYSIN DD #* 

LABEL INITT  SER=001234 
LABEL INITT  SER=001244 
LABEL INITT  SER=001254 
LABEL INITT  SER=001264 
LABEL INITT  SER=001274 
LABEL INITT  SER=001284 
LABEL INITT  SER=001294 
LABEL INITT  SER=001304 
/* 


In this example, serial number TAPE] is to be placed on a 2400 tape unit, and 
serial numbers 001234 and 001235 are to be placed on two 2400-4 tape units. 
The labels are to be written in EBCDIC at 800 and 1600 bits per inch. 


The example follows: 


// LABELS JOB 09#990,BROWN,MSGLEVEL=( 1,1 ) 

if EXEC PGM=IEHINITT 

//SYSPRINT DD SYSOUT=A 

//LABEL1 DD  DCB=DEN=2,UNIT=(2400,1,DEFER) 

//LABELZ DD DCB=DEN=3, UNIT=( 2400-4,1,DEFER) 
//SYSIN DD * 

LABEL 1 PEL SER=TAPE 1 

LABEL2 INITT SER=001234,NUMBTAPE=2 

/* 

Note: If 2400 tape units are not available for allocation and the system 


configuration includes 3400 tape units, a 3400 tape unit may be allocated by 
default. 
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IEHIOSUP Program 


Cc IEHIOSUP is a system utility (VS1 only—not supported under VS2) used to 
update TTR entries in the transfer control tables of the supervisor call library 
(SVC library). (See “Introduction” for general system utility information.) 
Because of the way SVC routines are loaded, it is necessary to update TTR 
entries after changing or replacing a module. IEHIOSUP automatically updates 
the TTR entries. IEHIOSUP must be used after: 


e The SVC library is moved. 


e The OPEN, CLOSE, TCLOSE, EOV, FEOV, SCRATCH, ALLOCATE, 
IEHATLAS,SETPRT, STOW, or any Machine-Check Handler (MCH) 
recovery management module is changed or replaced in the SVC library. 


Input and Output 


IEHIOSUP uses as input an object data set (SYS1.SVCLIB) that contains the 
transfer control tables that are to be updated. 


IEHIOSUP produces as output a message data set that contains any error 
messages generated during the execution of the program. 


IEHIOSUP produces a return code to indicate the results of program execution. 
The return codes and their interpretations are: 


e« QO, which indicates successful completion. 


e 12, which indicates an unrecoverable error. The job step is terminated. 


C Control 


IEHIOSUP is executed or invoked with job control statements. No utility control 
Statements are required. 


Job Control Statements 
Table 36 shows the job control statements necessary for using IEHIOSUP. 


Table 36. IEHIOSUP Job Control Statements 


Statement Use 
JOB Initiates the job. 
EXEC Specifies the program name (PGM=IEHIOSUP) or, if the job control 


statements reside in a procedure library, the procedure name. 
SYSPRINT DD _ Defines a sequential message data set. 


SYSUT1I DD Defines the object data set (SYSI.SVCLIB). The DSNAME, DISP, UNIT, 
and VOLUME parameters should be included. 


If the SYS1.SVCLIB data set is cataloged, the UNIT and VOLUME parameters 
are not required on the SYSUT1 DD statement. 


Restrictions 


¢« The block size for the SYSPRINT data set must be a multiple of 121. Any 
blocking factor can be specified. 
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IEHIOSUP Examples 


IEHIOSUP Example 1 


IEHIOSUP Example 2 
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The following examples illustrate some of the uses of IEHIOSUP. Table 37 can 
be used as a quick reference guide to IEHIOSUP examples. The numbers in the 
“Example” column point to examples that follow. 


Table 37. IEHIOSUP Example Directory 


Data Set 
Operation Organization Device Comments Example 
UPDATE Partitioned, 2314 Disk, SVC library is to be updated. 
Sequential system output SYS1.SVCLIB is not cataloged. 
device System output device is a printer. | 
UPDATE Partitioned, 3330 Disk, SVC library is to be updated. 
Sequential system output SYS1.SVCLIB is cataloged. System 
device output device is a printer. 2 


In this example, the TTR entries in the SVC library are to be updated. 
The example follows: 


J / TYRUPDTE JOB 

ee EXEC PGM=IEHIOSUP 

IF SVSUL DD DSNAME=SYS1.SVCLIB, DISP=OLD,UNIT=2314, 
// VOLUME=SER=111111 

//SYSPRINT DD SYSOUT=A 

/* 


The control statements are discussed below: 


¢ SYSUT1 DD defines the object data set (the SYS1.SVCLIB data set). 
« SYSPRINT DD defines the message data set. 


In this example, the TTR entries in the SVC library are to be updated. 
The example follows: 


//SVCUPDTE JOB 

Ty EXEC PGM=IEHIOSUP 

fp ost DD DSNAME=SYS1.SVCLIB, DISP=OLD 
//SYSPRINT DD SYSOUT=A 


/* 
The control statements are discussed below: 


¢ SYSUT1 DD defines the object data set (the SYS1.SVCLIB data set). 
Because the data set is cataloged, UNIT and VOLUME parameters are not 
required. 


¢ SYSPRINT DD defines the message data set. 


J 


L 
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Listing Catalog Entries 


IEHLIST is a system utility used to list entries in a catalog, entries in the 
directory of one or more partitioned data sets, or entries in a volume table of 
contents. (See “Introduction” for general system utility information.) Any 
number of listings can be requested in a single job. 


IEHLIST lists all catalog entries that are part of the structure of a fully-qualified, 
data set name. Figure 48 shows an index structure for which IEHLIST lists 
fully-qualified names A.B.D.W, A.B.D.X, A.B.E.Y, and A.B.E.Z. Because A.C.F 
does not represent a cataloged data set (that is, the lowest level of qualification 
has been deleted), it is not a fully-qualified name, and it is not listed. 


Figure 48. Index Structure—Listed by IEHLIST 


Listing a Partitioned Data Set Directory 


Edited Format 


IEHLIST can list up to ten partitioned data set directories in a single application 
of the program. A partitioned directory is composed of variable length records 
blocked into 256-byte blocks. Each directory block can contain one or more 
entries which reflect member (and/or alias) names and other attributes of the 
partitioned members in edited and unedited format. 


Figure 49 shows a directory block as it exists in storage. 


econ: esl eh Ee ee ss 
eee ) 
Peon [oe] en ee el 
ae 
se ce 
C 
— —_ 
Figure 49. Sample Directory Block a 


IEHLIST optionally provides the following information, which is obtained from 
the applicable partitioned data set directory, when an edited format is requested: 


e Member name 


e Entry point 
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¢ Attributes 

e Relative address of start of member 

e Relative address of start of text 

e Contiguous main storage requirements J 
e Length of first block of text 

¢ Origin of first block of text 

e System status indicators 

e Other information 


Before printing the directory entries on the first page, an index is printed 
explaining the asterisk (*) following a member name, the attributes (field 3), 
and other information (field 10). Under the ATTRIBUTE INDEX, the meaning 
of each attribute bit is explained; under the OTHER INFORMATION INDEX, 
scatter and overlay format data is described positionally as it appears in the 
listing. 


Each directory entry occupies one printed line, except when the member name is 
an alias and the main member name and associated entry point are available. 
When this occurs, two lines are used and every alias is followed by an asterisk. 


Note: The FORMAT option applies only to a partitioned data set whose 
members have been created by the Linkage Editor (that is, the directory entries 
are at least 34 bytes long). If a directory entry is less than 34 bytes, a message is 
issued and the entry is printed in unedited format; if the entry is longer than 34 
bytes, it is assumed that it is created by the Linkage Editor. 


Figure 50 shows an edited entry for a partitioned member (IEANUCO1). The 
entry is shown as it is listed by the IEHLIST program. 


MEMBER ENTRY ATTR REL ADDR-HEX CONTIG LEN 1st ORG Ist SSI OTHER 
NAME PT-HEX HEX BEGIN TStTXT STOR-DEC TXT-DEC TXT-HEX INFO INFORMATION 


IEANUCO1 OOQ000 0662 000003 000104 00035643 01024 000000 ABSENT SCTR=000102,00168,00316,04,04 


Figure 50. Edited Partitioned Directory Entry 


Unedited (Dump) Format 
The user may choose the unedited format. If this is the case, IEHLIST lists each 
member separately. 


Figure 51 shows how the information in Figure 49 is listed. 


Note: A listing such as that shown in Figure 49 can also be obtained by using 
IEBPTPCH (see “IEBPTPCH Program’’). 


MEMBA_ TTR USER DATA 
MEMBB_ TTR USER DATA 
MEMBC_ TTR USER DATA 
MEMBn TTR USER DATA 


Figure 51. Sample Partitioned Directory Listing 
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To correctly interpret user data information, the user must know the format of 
the partitioned entry. The formats of directory entries are discussed in OS/VS1 


System Data Areas, SY28-0605, and OS/VS2 System Data Areas, 
SY 28-0606. 
( Listing a Volume Table of Contents 


IEHLIST can be used to list, partially or completely, entries in a specified volume 
table of contents (VTOC). The program lists the contents of selected data set 
control blocks (DSCBs) in edited or unedited form. 

Edited Format 


Two edited formats are available. One is a comprehensive listing of the DSCBs 
in the VTOC. It provides the status and attributes of the volume, and describes 
in depth the data sets residing on the volume. This listing includes: 


e Logical record length and block size 
e Initial and secondary allocations 

e Upper and lower limits of extents 

e Alternate track information 

e Available space information, in detail 
e Option codes 

e« Record formats 


A VTOC consists of as many as seven types of DSCBs which contain 
information about the data sets residing on the volume: 


e Identifier DSCB—Format 1 
e Index DSCB—Format 2 
L e Extension DSCB—Format 3 
e VTOC DSCB—Format 4 
e Free Space DSCB—Format 5 
e Shared Extent DSCB—Format 6 = 
e Free VTOC DSCB—Format 0 


The first DSCB in a VTOC (and on your listing) is always a VTOC (Format 4) 
DSCB. It defines the scope of the VTOC itself; that is, it contains information 
about the VTOC and the volume rather than the data sets referenced by the 
VTOC. 


The VTOC (Format 4) DSCB is followed, when necessary, by the Free Space 
(Format 5) DSCB, which describes the space available on the volume for 
allocation to other data sets. More than one Format 5 DSCB may be required to 
describe the available space on a volume because each Format 5 DSCB describes 
only 26 extents. 


The Format 4 and Format 5 DSCBs are followed, in any order, by Format 1, 2, 
3, or 6 DSCBs. 


Each Identifier (Format 1) DSCB contains information about a particular data 
set residing on the volume. This type of DSCB describes the characteristics and 
up to three extents of the data set. 


For data sets having indexed-sequential organization, additional characteristics 
( are specified in an Index (Format 2) DSCB pointed to by the Identifier (Format 
1) DSCB. 
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Additional extents are described in an Extension (Format 3) DSCB pointed to by 
the Identifier (Format 1) DSCB or in the Index (Format 2) DSCB for an 
indexed-sequential data set. 


A Shared Extent (Format 6) DSCB is used for shared-cylinder allocation. It 

describes the extent of space (one or more contiguous cylinders) that is being 2 
shared by two or more data sets. The Shared Extent (Format 6) DSCB is 

pointed to by the VTOC (Format 4) DSCB. Subsequent Format 6 DSCBs are 

pointed to by the previous Format 6 DSCB. 


A Free VTOC Record (Format 0) DSCB, which indicates space available for 
another DSCB, is not listed by IEHLIST. They are 140-byte records, consisting 
of binary zeros, that are overwritten with format 1, 2, 3, and 6 DSCBs when a 
new data set is allocated, and with Format 5 DSCBs when space is released. 


Figure 52 shows a sample listing of the edited format. This sample illustrates how 
each DSCB will appear on a listing, although in many cases the VTOC may not 
contain all possible types. The information is in columns, with the values or 
numbers appearing underneath each item’s heading. 


SYSTEMS SUPPORT UTILITIES---IEHLIST 


CONTENTS OF VTOC ON VOL EXAMPL 


FORMAT 4 DSCB NO AVAIL/MAX DSCB /MAX DIRECT NO AVAIL NEXT ALT FORMAT 6 LAST FMT 1 VTOC EXTENT THIS DSCB 
DSCBS PER TRK BLK PER TRK ALT TRK- TRK(C~-H) (C-H-R) DSCB( C-H-R )/LOW(C-H) HIGH(C-H) (C-H-R) 
154 16 10 30 200 5 0 5 5 0 5 9 5 0 1 
FORMAT 5 DSCB A = NUMBER OF TRKS IN ADDITION TO FULL CYLS IN THE EXTENT 
TRK FULL TRK FULL TRK FULL TRK FULL TRK FULL TRK FULL 
ADDR CYLS A ADDR CYLS A ADDR CYLS A ADDR CYLS A ADDR CYLS A ADDR CYLS A 
17 3 3 110 189 ) 


DSCB( C-H-R ) a 2 


DATA SET NAME ID SER NO SEQ NO CREDT EXPDT NO EXT DSORG RECFM OPTCD- BLKSIZE 
EXAMPLE.OF. COMBINED. FORMATS .ONE.AND. TWO 1 EXAMPL 1 36699 27469 ] IS F 100 


LRECL KEYLEN INITIAL ALLOC 2ND ALLOC/LAST BLK PTR{ T-R-L) USED PDS BYTES FMT 2 OR 3(C-H-R)/DSCB(C-H-R) 
100 4 ABSTR 0 0 3 5 0 4 


EXTENTS NO LOW( C-H) HIGH(C-H) 
0 6 0 10 9 


2MIND( M-B-C-H )/3MIND( M~B-C-H )/L2MFN( C-H-R )/L3MIN( C-H-R })/CYLAD( M-B-C-H )/ADLIN( M-B-C-H )/ADHIN( M-B-C-H)/NOBYT/ NOTRK 
0 0 0 0 0 0 0 0 0 0 0 0 0 0 10 10 9 0 0 0 0 10 10 9 70 Q 


LTRAD( C~H-R )/LCYAD( C-H-R )/LMSAD( C-H-R)/LPRAD(M-B-C-H-R) /NOLFV /CYLOV/ TAGDT/ PRCTR / OVRCT/ RORG1/PTRDS(C-H-R ) 
6 0 3 10 9 1 0 0 0 10 6 1 12 1 0 20 0 0 
----UNABLE TO CALCULATE EMPTY SPACE 


DATA SET NAME ID SER NO SEQ NO CREDT EXPDT NO EXT DSORG RECFM OPTCD- BLKSIZE 
EXAMPLE.OF.COMBINED. FORMATS .ONE.AND. THREE 1 EXAMPL 1 36699 27069 16 PS Vv 3504 


LRECL KEYLEN INITIAL ALLOC 2ND ALLOC/LAST BLK PTR(T-R-L) USED PDS BYTES FMT 2 OR 3(C-H-R)/DSCB(C-H-R ) 
3500 R 1 15 1 1723 6 5 0 
EXTENTS 


LOW( C-H LOW( C-H HIGH(C-H N LOW( C-H HIGH( C-H 
0 0 0 0 0 


NO ) 
0 1 3 
3 a 6 
6 7 9 
9 10 1 2 

12 13 1 5 

15 


[I NwWwone-— 


---ON THE ABOVE DATA SET,THERE ARE QO EMPTY TRACK(S). 


THERE ARE 192 EMPTY CYLINDERS PLUS 3 EMPTY BRACKS ON THIS VOLUME 
THERE ARE 154 BLANK DSCBS IN THE VTOC ON THIS VOLUME 


Figure 52. Sample Printout of a Volume Table of Contents 


The second edited format is an abbreviated description of the data sets. It is 
provided by default when no format is requested specifically. It provides the 
following information: 


« Data set name 
e Creation date 
¢« Expiration date 


e Password indication 
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¢ Organization of the data set 
e Extent(s) 
e Volume serial number 


( The last line in the listing indicates how much space remains in the VTOC. 


Unedited (Dump) Format 


This option produces a complete hexadecimal listing of the DSCBs in the VTOC. 
The listing is in an unedited dump form, requiring the user to know the various 
formats of applicable DSCBs. The VTOC overlay for IEHLIST listings of 
VTOCs in dump format (Order Number ZM08-0033) is useful in identifying the 
fields of the DSCBs. 


Refer to OS/VSI System Data Areas , SY28-0605, or OS/VS2 System Data 
Areas , SY28-0606, for a discussion of the various formats that data set control 
blocks can assume. 


Input and Output 
IEHLIST uses the following input: 


e One or more source data sets that contain the data to be listed. The input data 
set(s) can be: (1) a WTOC data set, (2) a partitioned data set, or (3) a 
catalog data set (SYSCTLG). 


e A control data set, which contains utility control statements that are used to 
control the functions of IEHLIST. 


IEHLIST produces as output a message data set, which contains the result of the 
IEHLIST operations. The message data set includes the listed data and any error 
messages. 


< IEHLIST produces a return code to indicate the results of program execution. 
The return codes and their meanings are: 


e 00, which indicates successful completion. 


e 08, which indicates that an error condition caused a specified request to be 
ignored. Processing continues. 


e 12, which indicates that a permanent input/output error occurred. The job is 
terminated. 


¢ 16, which indicates that an unrecoverable error occurred while reading the 
data set. The job is terminated. 


Control 


IEHLIST is controlled by job control statements and utility control statements. 
The job control statements are used to execute or invoke IEHLIST and to define 
the data sets used and produced by IEHLIST. 


Utility control statements are used to control the functions of the program and to 
define those data sets or volumes to be modified. 


Job Control Statements 
Table 38 shows the job control statements necessary for using IEHLIST. 
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Table 38. IEHLIST Job Control Statements 


Statement Use 
JOB Initiates the job. 
EXEC Specifies the program name (PGM=IEHLIST) or, if the job control 


statements reside in a procedure library, the procedure name. Additional 
PARM information can be specified to control the number of lines printed 
per page. See ““PARM Information on the EXEC Statement” below. 


SYSPRINT DD _ Defines a sequential message data set. 


anynamel DD Defines a permanently mounted volume. 
anyname2 DD Defines a mountable device type. 
SYSIN DD Defines the control data set. The control data set normally follows the job 


control language in the input stream; however, it can be defined as an 
unblocked sequential data set or member of a procedure library. 


The ‘‘anynamel’’ DD statement can be entered: 
//anynamel DD UNIT=xxxx, VOLUME=SER=xxxxxx, DISP=OLD 


The UNIT and VOLUME parameters define the device type and volume serial 
number. The DISP=OLD specification prevents the inadvertent deletion of the 
data set. This statement is arbitrarily assigned the ddname DD1 in the IEHLIST 
examples. 


When deferred mounting is required, the ““anyname2”’ DD statement can be 
entered: 


//anyname2 DD UNIT=(xxxx,, DEFER),, VOLUME=(PRIVATE.,...), DISP=OLD 


See ‘Appendix C: DD Statements for Defining Mountable Devices’’ for 
information on defining mountable devices. This statement is arbitrarily assigned 
the ddname DD2 in the IEHLIST examples. Statements defining additional 
mountable devices are assigned ddnames DD3, DD4, etc. 


With the exception of the SYSIN and SYSPRINT DD statements, all DD 
statements in this table are used as device allocation statements, rather than as 
true data definition statements. 


e« The block size for the SYSPRINT data set must be a multiple of 121. The 
block size for the SYSIN data set must be a multiple of 80. Any blocking 
factor can be specified for these block sizes. 


e An “anynamel’’ DD statement must be included for each permanently 
mounted volume referred to in the job step. (The system residence volume is 
considered to be a permanently mounted volume.) 


e An “anyname2’’ DD statement must be included for each mountable device to 
be used in the job step. 


e Because IEHLIST modifies the internal control blocks created by device 
allocation DD statements, IEHLIST job control statements must not include 
the DSNAME parameter. (All data sets are defined explicitly or implicitly by 
utility control statements. ) 


e When IEHLIST is dynamically invoked in a job step containing another 
program, the DD statements defining mountable devices for IEHLIST must be 
included in the job stream prior to DD statements defining data sets required 
by the other program. 


PARM Information on the EXEC Statement 


Additional information can be specified in the PARM parameter of the EXEC 
statement to control the number of lines printed per page. The PARM parameter 
can be coded: 


PARM='LINECNT=xx’ 


The LINECNT parameter specifies the number of lines, xx, to be printed per 
page; xx is a decimal number from 01 through 99. If LINECNT is not specified, 
58 lines are printed per page. The PARM field cannot contain embedded blanks, 
zeros, or any other PARM keywords, or the default of 58 is used. 


Utility Control Statements 


LISTCTLG Statement 


LISTPDS Statement 


IEHLIST is controlled by the following utility control statements: 


¢ LISTCTLG statement, which is used to request a listing of all or part of a 
catalog. 


e LISTPDS statement, which is used to request a directory listing of one or 
more partitioned data sets. 


e LISTVTOC statement, which is used to request a listing of all or part of a 
volume table of contents. 


The LISTCTLG statement is used to request a listing of either the entire catalog 
or a specified portion of the catalog (SYSCTLG data set). The listing includes 
the fully-qualified name of each applicable cataloged data set and the serial 
number of the volume on which it resides. Empty index levels are not listed. 


The format of the LISTCTLG statement is: 


[label] LISTCTLG [VOL= device = serial | 
[NODE= name } 


where: 


VOL= device = serial 
specifies the device type and volume serial number of the control volume on 
which the specified portion of the catalog resides. If VOL is omitted, the 
catalog is assumed to reside on the system residence volume. 


NODE= name 
specifies a qualified name. All data set entries whose names are qualified by 
this name are listed. If NODE is omitted, all data set entries are listed. 


Note: General catalog information (one-level data sets, alias entries, and CVOL 
pointers) is printed prior to the printing of an entire catalog or node. 


The LISTPDS statement is used to request a directory listing of one or more 
partitioned data sets that reside on the same volume. 


The format of the LISTPDS statement is: ae 
[Jabel] LISTPDS |DSNAME=(name[,name]...) sue ope 
[VOL= device = serial | Mg ip OW Sp ah 


{DUMP} 
{FORMAT} 
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where: 


DSNAME=( name [, name |...) 
specifies the fully qualified names of the partitioned data sets whose 
directories are to be listed. A maximum of ten names is allowed. If the list 
consists of a single name, the parentheses can be deleted. 2 


VOL= device = serial 
specifies the device type and volume serial number of the volume on which the 
partitioned data sets reside. If VOL is omitted, the data sets are assumed to 
reside on the system residence volume. 


DUMP 
specifies that the listing is to be in unedited, hexadecimal form. 


FORMAT 
specifies that the listing is to be edited for each directory entry. 


Before printing the directory entries on the first page, an index is printed 
explaining the attributes (field 3) and other information (field 10). 
ATTRIBUTE INDEX explains each attribute bit, OTHER INFORMATION 
INDEX explains scatter and overlay format data as it appears in the listing. 


Note: The LISTPDS statement may be used only on a partitioned data set whose 
members have been created by the linkage editor. Members that have not been 
created by the linkage editor cause their directory entries to be listed in unedited 
(DUMP) format. 


The LISTVTOC statement is used to request a partial or complete listing of the 
entries in a specified volume table of contents. 


The format of the LISTVTOC statement is: 


DUMP 
specifies that the listing is to be in unedited, hexadecimal form. If both DUMP 
and FORMAT are omitted, an abbreviated edited format is generated by 
default. 


FORMAT 
specifies that a comprehensive edited listing is to be generated. If both 
FORMAT and DUMP are omitted, an abbreviated edited format is generated 
by default. 


DATE= dddyy 
specifies that each entry that expires before this date is to be flagged with an 
asterisk (*) in the listing. This parameter applies only to the abbreviated edited 
format. The date is represented by ddd, the day of the year, and yy, the last 
two digits of the year. If DATE is omitted, no asterisks appear in the listing. 


VOL= device = serial 
specifies the device type and volume serial number of the volume whose table 
of contents is to be listed. If VOL is omitted, the system residence volume is 


assumed. . j 


DSNAME=( name [, name |...) 
specifies the fully qualified names of the data sets whose entries are to be 
listed. A maximum of ten names is allowed. If DSNAME is omitted, the entire 
volume table of contents is listed. 


C IEHLIST Examples 
The following examples illustrate some of the uses of IEHLIST. Table 39 can be 
used as a quick reference guide to IEHLIST examples. The numbers in the 
“Example” column point to examples that follow. 
Table 39. IEHLIST Example Directory 
Operation Device Comments Example 
LIST 2314 Disk, Source catalog is to be listed on the 
system output system output device. 
device I 
LIST 2314 Disk, Three catalogs and part of a fourth 
system residence are to be listed on the system 
device, system output device. 
output device p) 
LIST 2314 or 2319 Three partitioned directories are to 
Disk,' 3330 be listed on the system output device. 
Disk, system 
output device 3 
LIST 2314 Disk, Volume table of contents is to be 
system output listed in edited form; selected 
device data set control blocks are listed 
in unedited form. 4 
' Note that the 2319 disk is functionally equivalent to the 2314 disk; to use the 2319, specify 
2314 in the control statement. 
( Note: In the IEHLIST examples, the EXEC statement and the SYSPRINT DD 


statement can be replaced with the following job control statement: 
// EXEC PROC=LIST 


The EXEC statement invokes the following IBM-supplied cataloged procedure: 


//LIST EXEC PGM=IEHLIST,REGION=44K 
//DDSRV DD VOLUME=REF=SYSI.SVCLIB,DISP=OLD 
//SYSPRINT DDSYSOUT=A 


) : ee 

IEHLIST Example 1 
In this example a catalog residing on a 2314 volume (231400) is to be listed. 
The example follows: 


J//LISTCAT- JOB. 098550, BLUE 


aA EXEC PGM=IEHLIST 

J /SYSPRINT- DD SYSOUT=A 

{7 OD2 DD UNIT=2314, VOLUME=SER=231400,DISP=OLD 
//SYSIN DD * 


LISTCTLG VOL=2314=231400 
/* 


The control statements are discussed below: 


e DD2 DD defines a mountable device on which the volume containing the 
source catalog is mounted. 


( e SYSIN DD defines the control data set, which follows in the input stream. 
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e LISTCTLG defines the source volume and specifies the list operation. 


Note: The data set name of the catalog data set is SYSCTLG. 


IEHLIST Example 2 


In this example a catalog residing on the system residence volume, two catalogs ~ 
residing on 2314 volumes, and a portion of a catalog residing on a 2314 volume, 
are to be listed. 


The example follows: 


//LISTCATS JOB 09#550, BLUE 


Ves EXEC PGM=IEHLIST 

//SYSPRINT DD SYSOUT=A 

//DD1 DD UNIT=3330, VOLUME=SER=111111,DISP=OLD 
//DD2 DD UNIT=(2314,,DEFER),DISP=OLD, 


// VOLUME=( PRIVATE, ,SER=( 231400) ) 
Jf FSTSIN DD * 

LISTCTLG 

ELST LLG VOL=2314=231400 

bis Tels VOL=2314=231401 

BESTCTLG VOL=2314=231402,NODE=A.B.C 
/* 


The control statements are discussed below: 


« DD1 DD defines a system residence device. (The first catalog to be listed 
resides on the system residence volume. ) 


e DD2 DD defines a mountable device on which each 2314 volume is mounted 
as it is required by the program. 


e SYSIN DD defines the control data set, which follows in the input stream. 


e The first LISTCTLG statement indicates that the catalog residing on the 
system residence volume is to be listed. ) 


e The second and third LISTCTLG statements identify two 2314 disk volumes 
containing catalogs to be listed. 


e The fourth LISTCTLG statement identifies a 2314 volume containing a 
catalog that is to be partially copied. All data set entries whose beginning 
qualifiers are “‘A.B.C”’ are copied. 


IEHLIST Example 3 


In this example, a partitioned directory existing on the system residence volume 
is to be listed. In addition, two partitioned directories existing on a 2314 or 2319 
volume are to be listed. 


The example follows: 


f/ULSTPDLIR: JOB. 094550, BLUE 


Oe: EXEC PGM=IEHLIST 

//SYSPRINT DD SYSOUT=A 

//DD1 DD UNIT=3330,VOLUME=SER=111111,DISP=OLD 
J JDD2 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 
//SYSIN DD * 


LISTPDS DSNAME=PARSET1 
LISTPDS  DSNAME=( PART1,PART2 ), VOL=2314=231400 
/ * 


The control statements are discussed below: 


e DD1 DD defines the system residence device. 


e DD2 DD defines a mountable device on which a 2314 volume (231400) is to , 
be mounted. J 
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e SYSIN DD defines the control data set, which follows in the input stream. 


e The first LISTPDS statement indicates that the partitioned data set directory 
belonging to data set PARSET1 is to be listed. This data set exists on the 
system residence volume. 


e The second LISTPDS statement indicates that partitioned directories belonging 
to data sets PART1 and PART2 are to be listed. These data sets exist on a 
2314 volume (231400). 


In this example, a volume table of contents in edited form, is to be listed. The 
edited listing is supplemented by an unedited listing of selected data set control 
blocks. 


The example follows: 


J//IASTVIO€ JOR. “098550; BLUE 


Ld EXEC PGM=IEHLIST 
//SYSPRINT DD SYSOUT=A 
//DD2 DD UNIT=2314, VOLUME=SER=231400,DISP=OLD 


L/P SLSIN DD * 

LISTVTOC FORMAT , VOL=2314=231400 

LiStTVlIOC DUMP , VOL=2314=231400,DSNAME=( SET1,SET2,SET3 ) 
/* 


The control statements are discussed below: 


e DD2 DD defines a mountable device on which the volume containing the 
specified volume table of contents is to be mounted. 


e SYSIN DD defines the control data set which follows in the input stream. 


e The first LISTVTOC statement indicates that the volume table of contents on 
the specified 2314 volume is to be listed in edited form. 


e The second LISTVTOC statement indicates that the data set control blocks 
representing data sets SET1, SET2, and SET3 are to be listed in unedited 
form. 
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IEHMOVE Program 


IEHMOVE is a system utility used to move or copy logical collections of 
operating system data. (See “Introduction” for general system utility 
information. ) 


IEHMOVE can be used to move or copy: 

e A data set residing on from one to five volumes. 
e A group of cataloged data sets. 

e A catalog, or portions of a catalog. 

e A volume of data sets. 


e Including or excluding data sets from a move or copy operation. 


The scope of a basic move or copy operation can be enlarged by: 
e Merging members from two or more partitioned data sets. 

e Including or excluding selected members. 

e Renaming moved or copied members. 

e Replacing selected members. 


If, for some reason, IEHMOVE is unable to successfully move or copy specified 
data, an attempt is made to reorganize the data and place it on the specified 
output device. The reorganized data—called an unloaded data set—is a 
sequential data set consisting of 80-byte blocked records that contain the source 
data and control information for subsequently reconstructing the source data as it 
originally existed. 


When an unloaded data set is moved or copied to a device that will support the 
data in its true form, the data is automatically reconstructed. For example, if the 
user attempts to move a partitioned data set to a tape volume, the data is 
unloaded to that volume. The user can recreate the data set simply by moving 
the unloaded data set to a direct access volume. 


A move operation differs from a copy operation in that a move operation 
scratches source data if the data set resides on a direct access source volume 
(and the expiration date has occurred if VS2), while a copy operation leaves 
source data intact. In addition, for cataloged data sets, a move operation updates 
the catalog to refer to the moved version (unless otherwise specified), while a 
copy operation leaves the catalog unchanged. 


Space can be allocated for a data set on a receiving volume either by the user 
(through the use of DD statements in a prior job step) or by IEHMOVE in the 
IEHMOVE job step. If the source data is unmovable (that is, if it contains 
location dependent code), the user should allocate space on the receiving volume 
using absolute track allocation to ensure that the data set is placed in the same 
relative location on the receiving volume as it was on the source volume. 
Unmovable data can be moved (or copied if VS2) if space is allocated by 
IEHMOVE, but the data will not be in the same location on the receiving 
volume as it was on the source volume. When data sets are to be moved (or 
copied if VS2) between unlike devices, a secondary allocation should be made to 
ensure that ample space is available on the receiving volume. 
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Space for a new data set cannot be allocated by the user under the following 
circumstances: 


¢ When the organization of the data set to be moved or copied is direct and the 
data set is not to be unloaded, IEHMOVE cannot determine whether the new 
data set is empty. 


e When a partitioned data set is being moved or copied as part of a move or 
copy volume operation and the data set is not to be unloaded. If the user does 
preallocate a partitioned data set in this case, no merging takes place. 


If IEHMOVE performs the space allocation for the new data set, the space 
requirement information of the old data set (if available) is used. This space 
requirement information is obtained from the DSCB of the source data set, if it 
is on a direct access device, or the control information in the case of an unloaded 
data set. 


If space requirement information is available, IEHMOVE uses this information to 
derive an allocation of space for the receiving volume, taking into account the 
differences in device characteristics, such as track capacity and overhead factors. 
However, when data sets with variable or undefined record formats are being 
moved or copied between unlike devices, no assumption can be made about the 
space that each individual record needs on the receiving device. 


In general, when variable or undefined record formats are to be moved or copied, 
IEHMOVE attempts to allocate sufficient space. This might cause too much 
space to be allocated under the following circumstances: 


e When moving or copying from a device with a relatively large block overhead 
to a device with a smaller block overhead, the blocks being small in relation to 
the block size. 


e When moving or copying from a device with a relatively small block overhead 
to a device with a larger block overhead, the blocks being large in relation to 
the block size. 


Note: Data sets with direct organization and variable record format always have 
the same amount of direct access space allocated by IEHMOVE. This practice 
preserves any relative track addressing system that might exist within the data 
sets. 


Note: When a data set has more than three extents and the space requirement 
for the remaining extents is more than eleven times the secondary allocation 
quantity, the data set should be allocated before performing the copy operation. 


A move or copy operation results in: (1) a moved or copied data set, (2) no 
action, or (3) an unloaded version of the source data set. These results depend 
upon the compatibility of the source and receiving volumes with respect to: 


e Size of the volumes. 

e Data set organization (sequential, partitioned, or direct access). 
e Movability of the source data set. 

e Allocation of space on the receiving volume. 


Two volumes are compatible with respect to size if (1) the source record size 
does not exceed the receiving track size, or (2) the receiving volume supports the 
track overflow feature and the output is to be written with track overflow. (Refer 
to “Job Control Statements” for notes on the track overflow feature.) When 
using direct access organizatfon, two volumes are compatible with respect to size 
if the source track capacity does not exceed the receiving track capacity. Direct 
access data sets moved or copied to a smaller device type or tape are unloaded. 


J 


If the user wishes to load an unloaded direct access data set, it must be loaded to 


the same device type from which it was originally unloaded. 


Table 40 shows the results of move and copy operations when the receiving 
volume is a direct access volume that is compatible in size with the source 
volume. The organization of the source data set is shown along with the 
characteristics of the receiving volume. 


Table 40. Move and Copy Operations—Direct Access Receiving Volume with Size 
Compatible with Source Volume 


Receiving Volume 


Characteristics Sequential Partitioned Direct Access 
Space allocated moved or copied moved or copied moved or copied 
by IEHMOVE 

(movable data) 

Space allocated moved or copied moved or copied no action 

by IEHMOVE 

(unmovable data) 

Space previously moved or copied moved or copied no action 
allocated, as yet 

unused 

Space previously no action moved or copied no action 
allocated, partially (merged) 

used 


Table 41 shows the results of move and copy operations when the receiving 
volume is a direct access volume that is not compatible in size with the source 
volume. The organization of the source data set is shown along with the 
characteristics of the receiving volume. 


Table 41. Move and Copy Operations—Direct Access Receiving Volume with Size 
Incompatible with Source Volume 


Receiving Volume 
Characteristics Sequential Partitioned Direct Access 


Space allocated unloaded unloaded unloaded 
by IEHMOVE 


Space previously unloaded unloaded no action 
allocated, as yet 
unused 


Space previously no action no action no action 
allocated, partially 
used 


Table 42 shows the results of move and copy operations when the receiving 
volume is not a direct access volume. The organization of the source data set is 
shown along with the characteristics of the receiving volume. 


Table 42. Move and Copy Operations—Non-Direct Access Receiving Volume 


Receiving Volume 


Characteristics Sequential Partitioned Direct Access 
Movable data moved or copied unloaded unloaded 
Unmovable data unloaded unloaded no action 


Space cannot be previously allocated for a partitioned data set that is to be 
unloaded unless the SPACE parameter in the DD statement making the 
allocation implies sequential organization. Direct data sets cannot be previously 


allocated because they cannot be differentiated from partially used existing direct 


data sets. 


IEHMOVE Program 281 


Reblocking 


If a move or copy operation is unsuccessful, the source data remains intact. 


If a move or copy operation is unsuccessful and space was allocated by 
IEHMOVE, all data associated with that operation is scratched from the 
receiving direct access volume. If the receiving volume was tape, it will contain a 
partial data set. 


If a move or copy operation is unsuccessful and space was previously allocated, 
no data is scratched from the receiving volume. If, for example, IEHMOVE 
moved 104 members of a 105-member partitioned data set and encountered an 
input/output error while moving the 105th member: 


e The entire partitioned data set is scratched from the receiving volume if space 
was allocated by IEHMOVE. 


« No data is scratched from the receiving volume if space was previously 
allocated. In this case, after determining the nature of the error, the user need 
move only the 105th member into the receiving partitioned data set. 


If a sequential data set is to be moved or copied and space attributes are not 
available either through a previous allocation or from the data set control block 
belonging to the source data set, IEHMOVE makes a default space allocation. 
The default allocation consists of a primary allocation of 72,500 bytes of storage 
(data and gaps) and up to 14 secondary allocations of 36,250 bytes each. 


When moving or copying a data set group or a volume containing 
password-protected data sets, the user must provide the password each time a 
data set is opened or scratched. 


IEHMOVE always moves or copies any user labels associated with an input data 
set. IEHMOVE does not take exits to a user’s label processing routines. 


Note: If a data set that has only user trailer labels is to be moved from a tape 
volume to a direct access volume, space must be previously allocated on the 
direct access volume to ensure that a track is reserved to receive the user labels. 


Data sets with fixed or variable records can be reblocked to a different block size 
by previously allocating the desired block size on the receiving volume. No 
reblocking can be performed when loading or unloading. 


When moving or copying data sets with undefined record format and reblocking 
to a smaller block size (that is, transferring records to a device with a track 
capacity smaller than the track capacity of the original device), the user must 
make the block size for the receiving volume equal to or larger than the size of 
the largest record in the data set being moved or copied. 


Moving or Copying a Data Set 
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IEHMOVE can be used to move or copy sequential, partitioned, and direct 
access data sets, as follows: 


e A sequential data set can be: (1) moved from one direct access or non-direct 
access volume to another (or to the same volume provided that it is a direct 
access volume), or (2) copied from one direct access or non-direct access 
volume to another (or to the same volume provided that the data set name is 
changed and the receiving volume is a direct access volume). 


e A partitioned data set can be: (1) moved from one direct access volume to 
another (or to the same volume) or, (2) copied from one direct access volume 
to another (or to the same volume provided that the data set name is 
changed). 


J 


e A direct access data set can be moved or copied from one direct access 
volume to another provided that the receiving device type is the same device 
type or a larger device type and that the record size does not exceed 32K. 


In addition, IEHMOVE can be used to move or copy multi volume data sets. To 
move or copy a multi volume data set, specify the complete volume list in the 
VOL=SER parameter on the DD statement. To move or copy a data set that 
resides on more than one tape volume, specify the volume serial numbers of all 
the tape volumes and the sequence numbers of the data set on the tape volumes 
in a utility control statement. (You must specify the sequence number even if the 
data set to be moved or copied is the only data set on a volume.) To move or 
copy a data set to more than one tape volume, specify the volume serial numbers 
of all the receiving volumes in a utility control statement. 


A data set with the unmovable attribute can be moved or copied from one direct 
access volume to another or to the same volume provided that space has been 
previously allocated on the receiving volume. Change the name of a data set to 
move or copy it to the same volume. 


When moving or copying a BDAM data set from one device to another device of 
the same type, relative track and relative block integrity are maintained. 


When moving or copying a BDAM data set to a larger device, relative track 
integrity is maintained for data sets with variable or undefined record formats; 
relative block integrity is maintained for data sets with fixed record formats. 


When moving or copying a BDAM data set to a smaller device or a tape, the 
data set is unloaded. An unloaded data set is loaded only when it is moved or 
copied to the same device type from which it was unloaded. 


Table 43 shows basic and optional move and copy operations for sequential and 
partitioned data sets. 
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Table 43. Moving and Copying Sequential and Partitioned Data Sets 


Operation Basic Actions Optional Actions 

Move Move the data set. For direct access, Prevent automatic cataloging of the 

Sequential scratch the source data. For cataloged moved data set. Rename the moved 
to refer to the moved data set. data set. 

Move Move the data set. For direct access, Prevent automatic cataloging of the 

Partitioned scratch the source data. For cataloged moved data set. Rename the moved 
data sets, update the catalog to refer data set. Reallocate directory space. 
to the moved data set. (Not possible if the space was not 

allocated by IEHMOVE during this 
move function.) Perform a merge 
operation using members from two or 
more data sets. Move only selected 
members. Replace members. Unload 
the data set. 

Copy Copy the data set. The source data set Uncatalog the source data set. Catalog 
is not scratched. The catalog is not the copied data set on the receiving 
updated to refer to the copied data set. volume. Rename the copied data set. 

Copy Copy the data set. The source data Is Uncatalog the source data set. Catalog 

Partitioned not scratched. The catalog is not the copied data set on the receiving 


updated to refer to the copied data 
scl. 


volume. Rename the copied data set. 
Reallocate directory space. (Not 
possible if the space previously 
allocated is partially used.) Perform a 
merge Operation using members from 
two or more data sets. Copy only 
selected members. Replace members. 
Unload the data set. 


IEHMOVE moves or copies partitioned members in the order in which they 


appear in the partitioned directory. That is, moved or copied members are placed 
in collating sequence on the receiving volume. 


Figure 53 shows a copied partitioned data set. Note that the members are copied 
in the order in which they appear in the partitioned directory. IEBCOPY can be 
used to copy data sets whose members are not to be collated. 


Source data set 


Copied data set 


Directory Directory 


Members Members 


Figure 53. Partitioned Data Set Before and After an IEHMOVE Copy Operation 


Members that are merged into an existing data set are placed, in collating 
sequence, after the last member in the existing data set. 


Figure 54 shows members from one data set merged into an existing data set. 
Note that members A, C, and G from the existing data set are copied to the 
receiving volume before members B and F are copied from the source data set. 
Members B and F are copied in collating sequence. 
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Figure 54. Merging Two Data Sets Using IEHMOVE 


Figure 55 shows how members from two data sets are merged into an existing 
data set. Members from additional data sets can be merged in a like manner. 
Note that members A, C, and G are copied from the existing data set before any 
members are copied from the source data sets. Members F, B, D, and E from the 
source data sets are copied in collating sequence. 
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Figure 55. Merging Three Data Sets Using IEHMOVE 


Moving or Copying a Group of Cataloged Data Sets 


IEHMOVE can be used to move or copy a group of data sets that are cataloged 
on the same volume and whose names are qualified by one or more identical 
names. For example, a group of data sets qualified by the name A.B can include 
data sets named A.B.D and A.B.E, but could not include data sets named A.C.D 
or A.D.F. 


Additional data sets not belonging to the specified data set group can be included 
in the move or copy operation; data sets belonging to the group can be excluded. 
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If a group of data sets is moved or copied to magnetic tape, the data sets must 
be retrieved one by one by data set name and file-sequence number, or by 
file-sequence number for unlabeled or non-standard labeled tapes. 


IEHLIST can be used to determine the structure of the catalog. 


Table 44 shows basic and optional move and copy operations for a group of 
cataloged data sets. 


Table 44. Moving and Copying a Group of Cataloged Data Sets 


Operation Basic Actions Optional Actions 
Move group Move the data set group (excluding Prevent updating of the catalog. 
of cataloged password-protected data sets) to the Include password-protected data 
data sets specified volumes. Scratch the source sets in the operation. Include 
data sets (direct access only). additional data sets in the 
The catalog is not updated to refer to operation. Exclude data sets 
moved data sets. Merging is not done. from the operation. Unload 
data sets. 
Copy group Copy the data set group (excluding Include password-protected data 
of cataloged password-protected data sets). Source sets in the operation. Uncatalog 
data sets data sets are not scratched. The the source data sets. Catalog 
catalog is not updated to refer to the copied data sets on the 
copied data sets. Merging is not done. receiving volumes. Include 


additional data sets in the 
operation. Unload a data set or 
sets. 


Moving or Copying a Catalog 


IEHMOVE can be used to move or copy a catalog or portions of a catalog 
without copying the data sets represented by the cataloged entries. The 
SYSCTLG (system catalog) data set need not be defined on the receiving volume 
before the operation. If, however, SYSCTLG was defined before the operation, 
the data set organization must not have been specified in the DCB field. Moved 
or copied entries are merged with any existing entries on the receiving volume. 
Note that the receiving volume must be a direct access volume unless the catalog 
is to be unloaded. 


Table 45 shows basic and optional move and copy operations for the catalog. 


Table 45. Moving and Copying the Catalog 


Operation Basic Actions Optional Actions 

Move catalog Move entries from the catalog to the Exclude selected entries from 
specified direct access volume. operation. Move an unloaded 
Scratch the source volume. version of the catalog. Unload 


the catalog to the magnetic 
tape volume. 


Copy catalog Copy entries from the catalog to the Exclude selected entries from 
specified direct access device. The the operation. Copy an unloaded 
source catalog is not scratched. version of the catalog. Unload 


the catalog to a tape volume. 


Moving or Copying a Volume of Data Sets 
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IEHMOVE can be used to move or copy the data sets of an entire direct access 
volume to another volume or volumes. A move operation differs from a copy 
operation in that the move operation scratches source data sets, while the copy 
operation does not. For both operations, any cataloged entries associated with 
the source data sets remain unchanged. IEHPROGM can be used to uncatalog all 
of the cataloged data sets and recatalog them according to their new location. 


If the source volume contains a SYSCTLG data set, that data set is the last to be 
moved or copied onto the receiving volume. 


J 
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If a volume of data sets is moved or copied to tape, the data sets must be 
retrieved one by one by data set name and file-sequence number, or by 
file-sequence number for unlabeled or non-standard labeled tapes. 


When copying a volume of data sets, the user has the option of cataloging all 
source data sets in a SYSCTLG data set on a receiving volume. However, if a 
SYSCTLG data set exists on the source volume, error messages indicating that 
an inconsistent index structure exists are generated when the source SYSCTLG 
entries are merged into the SYSCTLG data set on the receiving volume. 


The move-volume feature does not merge partitioned data sets. If a data set on 
the volume to be moved or copied has a name identical to a data set name on 
the receiving volume, the data set is not moved, copied, or merged onto the 
receiving volume. 


Table 46 shows basic and optional move and copy operations for a volume of 
data sets. 


Table 46. Moving and Copying a Volume of Data Sets 


Operation Basic Actions Optional Actions 

Move a volume Move all data sets not protected by a Include password-protected data 

of data sets password to the specified direct access sets in the operation. Move to a 
volumes. Scratch the source data sets tape volume. 


for direct access volumes. The catalog 
is not updated. 


COPY a volume Copy all data sets not protected by a Include password-protected data 

of data sets password to the specified direct access sets in the operation. Catalog all 
volume. The source data sets are not copied data sets on the receiving 
scratched. volume (direct access only). 


Copy to a tape volume. 


Moving or Copying Direct Data Sets with Variable-Spanned Records 


IEHMOVE can be used to move or copy direct data sets with variable-spanned 
records from one direct access volume to a compatible direct access volume, 
provided that the record size does not exceed 32K. 


Because a direct access data set can reside on one to five volumes (all of which 
must be mounted during any move or copy operation), it is possible for the data 
set to span volumes. However, single variable-spanned records are contained on 
one volume. 


Relative track integrity is preserved in a move or copy operation for spanned 
records. Moved or copied direct access data sets occupy the same relative _ 
number of tracks that they occupied on the source device. 


If a direct data set is unloaded (moved or copied to a smaller device or tape), it 
must be loaded back to the same device type from which it was originally 
unloaded. 


When moving or copying variable-spanned records to a larger device, record 
segments are combined and re-spanned if necessary. Because the remaining track 
space is available for new records, variable-spanned records are unloaded before 
being moved or copied back to a smaller device. 


If a user wishes to create a direct data set without using data management 
BDAM macros, all data management specifications must be followed. Special 
attention must be given to data management specifications for RO track capacity 
record content, segment descriptor words, and the BFTEK=R parameter. 


When moving or copying a multivolume data set, the secondary allocation for direct 
data sets should be at least two tracks. (See the ““WRITE SZ” macro in OS/VS Data 
Management Macro Instructions, GC26-3793.) 
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Input and Output 
IEHMOVE uses the following input: 


e One or more data sets, which contain the data to be moved, copied, or merged 


7 
into an output data set. } 


¢ A-control data set, which contains utility control statements that are used to 
control the functions of the program. 


e A work data set, which is a work area used by IEHMOVE. 
IEHMOVE produces the following output: 
e An output data set, which is the result of the move, copy, or merge operation. 


e A message data set, which contains informational messages (for example, the 
names of moved or copied data sets) and error messages, if applicable. 


IEHMOVE produces a return code to indicate the results of program execution. 
The return codes and their meanings are: 


e OO, which indicates successful completion. 


e 04, which indicates that a specified function was not completely successful. 
Processing continues. 


e 08, which indicates a condition from which recovery is possible. Processing 
continues. 


e 12, which indicates an unrecoverable error. The job step is terminated. 


Control 


IEHMOVE is controlled by job control statements and utility control statements. 

The job control statements are used to execute or invoke the program, define the J 
devices and volumes used and produced by IEHMOVE, and prevent data sets 

from being deleted inadvertently. 


Utility control statements are used to control the functions of the program and to 
define those data sets or volumes that are to be used. 


Job Control Statements 
Table 47 shows the job control statements necessary for using IEHMOVE. 
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Table 47. IEHMOVE Job Control Statements 


Statement Use 
JOB Initiates the job. 


EXEC Specifies the program name (PGM=IEHMOVE) or, if the job control 
statements reside in a procedure library, the procedure name. This statement 
can include optional PARM information; see ““PARM Information on the 
EXEC Statement”’ below. 


SYSPRINT DD Defines a sequential message data set. The data set can be written onto a 
system output device, a magnetic tape volume, or a direct access volume. 


SYSUT1 DD Defines a volume on which a work data set required by IEHMOVE is placed. 


anynamel DD Defines a permanently mounted volume. (The system residence volume is 
considered to be a permanently mounted volume.) 


anyname2 DD Defines a mountable device type. 


tape DD Defines a tape volume to be used when moving or copying from or to a 7-track 
tape volume, a 9-track tape volume not having standard labels, or a 1600 bits 
per inch, 9-track tape volume on a single-density unit, or when copying to an 
800 bits per inch tape on a dual-density unit. 


SYSIN DD Defines the control data set. The data set, which contains utility control 
statements, usually follows the job control statements in the input stream; 
however, it can be defined either as an unblocked sequential data set or as a 
member of a procedure library. 


The SYSUT1 DD statement can be coded: 
//SYSUT1 DD UNIT=xxxx, VOLUME=SER=xxxxxx, DISP=OLD 


At least 3 utility work areas of 13, 13, and 26 contiguous tracks, respectively, 
must be available for work space on the volume defined by the SYSUT1 DD 
statement. (This figure is based on a 2314 being the work volume. If a direct 
access device other than a 2314 is used, an equivalent amount of space must be 
available.) 


The anynamel DD statement can be coded: 
//anynamel DD UNIT=xxxx, VOLUME=SER=xxxxxx, DISP=OLD 


In the anynamel DD statement, the UNIT and VOLUME parameters define the 
device type and volume serial number. The DISP=OLD specification prevents 
the inadvertent deletion of a data set. The anynamel DD statement is arbitrarily 
assigned the ddname DD1 in the IEHMOVE examples. 


The anyname2 DD statement can be coded: 


//anyname2 DD UNIT=xxxx, VOLUME=SER =xxxxxx, DISP=OLD 


When the number of volumes to be processed is greater than the number of 
devices defined by DD statements, there must be an indication (in the applicable 
DD statements) that multiple volumes are to be processed. This indication can be 
in the form of deferred mounting, as follows: 


//anyname2 DD UNIT=(xxxx,, DEFER), VOLUME=(PRIVATE....), 
if DISP=(...,KEEP) 


See ‘Appendix C: DD Statements for Defining Mountable Devices” for 
information on defining mountable devices. The anyname2 DD statement is 
arbitrarily assigned the ddname DD2 in the IEHMOVE examples. DD statements 
defining additional mountable device types are assigned names DD3, DD4, etc. 
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Restrictions 
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The tape DD statement can be coded: 


//tape DD DSNAME=xxxxxxxx, UNIT=xxxx, VOLUME=SER=xxxxxx, 
Ti DISP=(...,KEEP), _LABEL=(...,... ), DCB=(TRTCH=C, DEN=x) 


when 7-track tape is to be used. A utility control statement parameter refers to 
the tape DD statement for label and mode information. 


J 


The date on which a data set is moved or copied to a magnetic tape volume is 
automatically recorded in the HDR 1 record of a standard tape label if a TODD 
parameter is specified in a utility control statement. An expiration date can be 
specified by including the EXPDT or RETPD subparameters of the LABEL 
keyword in the DD statement referred to by a TODD parameter. 


To define a sequence number for a data set on a tape volume, or to specify a 
specific device (for example, unit address 190), you must use a utility control 
statement instead of a DD statement. To move or copy a data set from or to a 
tape volume containing more than one data set, specify the sequence number of 
the data set in a utility control statement. To move or copy a data set from or to 
a specific device, specify the unit address (rather than a group name or device 
type) in a utility control statement. To copy to a unit record or non-labeled tape 
volume, specify any standard name or number in a utility control statement. 


IEHMOVE automatically calculates and allocates the amount of space needed for 
the work areas. No SPACE parameter, therefore, should be coded in the 
SYSUT1 DD statement. If, in the EXEC statement, POWER=3 is specified, the 
work space requirement is three times the basic requirements, etc. 


With the exception of the SYSIN and SYSPRINT DD statements, all DD 

Statements shown in Table 47 are used as device allocation statements, rather 

than as true data definition statements. Because IEHMOVE modifies the internal 

control blocks created by device allocation DD statements, these statements must 

not include the DSNAME parameter. (AII data sets are defined explicitly or 2 
implicitly by utility control statements.) 


A merge operation requires that one DD statement defining a mountable device 
be present for each source volume containing data to be included in the merge 
operation. 


Prior space allocations can be made by specifying a dummy execution of 
IEHPROGM before the execution of IEHMOVE. 


Blocked-format data sets that do not contain user data TTRNs or keys can be 
reblocked or unblocked by including the proper keyword subparameters in the 
DCB operand of the DD statement used to previously allocate space for the data 
set. The new blocking factor must be a multiple of the logical record length 
originally assigned to the data set. (For a discussion of user data TTRNs, refer to 
OS/VS Data Management Services Guide , GC26-3783.) 


e The block size for the SYSPRINT data set must be a multiple of 121. The 
blocksize for the SYSIN data set must be a multiple of 80. Any blocking 
factor can be specified for these block sizes. 


e One anynamel DD statement must be included for each permanently mounted 
volume referred to in the job step. 


e One anyname2 DD statement must be included for each mountable device to 
be used in the job step. 
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e When IEHMOVE is dynamically invoked in a job step containing another 
program, the DD statements defining mountable devices for IEHMOVE must 
be included in the job stream prior to DD statements defining data sets 

C required by the other program. 


PARM Information on the EXEC Statement 


The EXEC statement for IEHMOVE can contain PARM information that is 
used by the program to allocate additional work space and/or control line density 
on Output listings. The EXEC statement can be coded, as follows: 


// EXEC PGM=IEHMOVE[,PARM= {‘POWER=n’} 
{POWER=n,LINECNT=xx’} 
{“LINECNT=xx’} 


The POWER=n parameter is used to request that the normal amount of space 
allocated for work areas be increased n times. The POWER parameter is used 
when 750 or more members are being moved or copied. The progression for the 
value of ni is: 


e POWER=2 when 750 to 1,500 members are to be moved or copied. 
e POWER#=3 when 1,501 to 2,250 members are to be moved or copied. 
«© POWER=4 when 2,251 to 3,000 members are to be moved or copied. 


If POWER=2, the work space requirement on the SYSUT1 volume is two times 
the basic requirement; if POWER=3, work space requirement is three times the 
basic requirement, etc. For example, if POWER=2, three areas of 26, 26, and 52 
contiguous tracks on a 2314 must be available. 


When moving or copying a catalog, the value of the POWER parameter can be 
calculated, as follows: 


( POWER=(10D + V + 20G)/4000 


where D is the total number of data sets, aliases, and generation data set entries 
(which is the number of data set names printed by IEHLIST when LISTCTLG is 
specified); V is the total number of volumes used by these data sets (which is the 
number of lines printed by IEHLIST when LISTCTLG is specified); and G is the 
number of generated data sets. The progression of the value of n when moving 
or copying a catalog is: 


e POWER=2 when 350 to 700 data sets are cataloged. 
¢ POWER=3 when 701 to 1050 data sets are cataloged. 
«© POWER=4 when 1051 to 1400 data sets are cataloged. 


The LINECNT=xx parameter specifies the number of lines per page in the 
listing of the SYSPRINT data set; xx is a two-digit number. 


Job Control Language for the Track Overflow Feature 


A data set containing track overflow records can be moved or copied if the 
source volume and the receiving volume are mounted on direct access devices 
that support the track overflow feature. (For BDAM data sets, the source and 
receiving devices must be the same device type.) 


A data set that was written without track overflow can be moved or copied with 
or without track overflow or vice versa if the following conditions are met: 


« Space was allocated for the data set prior to the request for a move or copy 
operation. 
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¢ The DD statement used for that allocation included the subparameter to 
specify the changed track overflow value and all other desired values. (The 
RECFM specifications assigned when the data set was originally created are 
overridden by the RECFM subparameter in this DD statement.) 


If space has not been allocated, or if RECFM was not specified when space was 
allocated, the data set is moved or copied in accordance with RECFM 
specifications that were made when the data set was originally created. 


The track overflow attribute is not retained for a sequential data set that is 
moved or copied to a device other than a direct access device. 


Utility Control Statements 


MOVE DSNAME Statement 
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IEHMOVE is controlled by the following utility control statements: 
e MOVE DSNAME statement, which is used to move a data set. 
¢ COPY DSNAME statement, which is used to copy a data set. 


¢ MOVE DSGROUP statement, which is used to move a group of cataloged 
data sets. 


¢ COPY DSGROUP statement, which is used to copy a group of cataloged data 
sets. 


e MOVE PDS statement, which is used to move a partitioned data set. 

e COPY PDS statement, which is used to copy a partitioned data set. 

¢e MOVE CATALOG, which is used to move cataloged entries. 

e COPY CATALOG statement, which is used to copy cataloged entries. 

¢e MOVE VOLUME statement, which is used to move a volume of data sets. 
e COPY VOLUME statement, which is used to copy a volume of data sets. 


In addition, there are four subordinate control statements that can be used to 
modify the effect of a MOVE DSGROUP, COPY DSGROUP, MOVE PDS, 
COPY PDS, MOVE CATALOG, or COPY CATALOG operation. The 
subordinate control statements are: 


e INCLUDE statement, which is used to enlarge the scope of a MOVE 
DSGROUP, COPY DSGROUP, MOVE PDS, or COPY PDS statement by 
including a member or data set not explicitly included by the statement it 
modifies. 


e EXCLUDE statement, which is used with a MOVE DSGROUP, COPY 
DSGROUP, MOVE PDS, COPY PDS, MOVE CATALOG, or COPY 
CATALOG statement to exclude data from the move or copy operation. 


e REPLACE statement, which is used with a MOVE PDS or COPY PDS 
Statement to exclude a member from a move or copy operation and to replace 
it with a member from another partitioned data set. 


¢ SELECT statement, which is used with MOVE PDS or COPY PDS statements 
to select members to be moved or copied and, optionally, to rename the 
specified members. 


The MOVE DSNAME statement is used to move a data set. The source data set 
is scratched. 


C 


COPY DSNAME Statement 


The format of the MOVE DSNAME statement is: 


where: 


DSNAME= name 
specifies the fully qualified name of the data set to be moved. 


TO= device = list 
specifies the volume or volumes to which the data set is to be moved. 


FROM= device = list 
specifies the volume or volumes on which the data set currently resides, if it is 
not cataloged. If the data set is cataloged, FROM should not be written. 


CVOL= device = serial 
specifies the device type and volume serial number of the volume on which the 
catalog search for the data set is to begin. If neither CVOL nor FROM is 
written, the data set is assumed to be cataloged on the system residence 
volume. 


UNCATLG 
specifies that the catalog entry pertaining to the data set is to be removed. 
This parameter should be used only if the source data set is cataloged. 
UNCATLG is ignored if the volume is identified by FROM. 


RENAMEZ= name 
specifies that the data set is to be renamed, and indicates the new name. 


FROMDD= ddname 
specifies the name of a DD statement from which DCB and LABEL 
information are obtained. This parameter is valid for data sets residing on 
magnetic tape volumes. 


TODD= ddname 
specifies the name of a DD statement from which DCB and LABEL 
information are obtained. This parameter, which is valid for data sets to be 
moved to tape volumes, describes the mode and label of the volume where the 
moved data set is to reside. RECFM, LRECL, and BLKSIZE information is 
ignored. 


If the data set is cataloged, the catalog is automatically updated unless 
UNCATLG is specified. 


The FROMDD and TODD parameters can be omitted for 800 bits per inch, 
9-track tape with standard labels on single-density units or for 1600 bits per 
inch, 9-track tape with standard labels on dual-density units. 


The COPY DSNAME statement is used to copy a data set. 
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The format of the COPY DSNAME statement is: 


; 


“grrr 


or ae reps 
where: 
DSNAME= name 
specifies the fully qualified name of the data set to be copied. 


TO= device = list 
specifies the volume or volumes on which the data set is to be copied. 


FROM= device = list 
specifies the volume or volumes on which the data set currently resides, if it is 
not cataloged. If the data set is cataloged, FROM should not be written. 


CVOL= device = serial 
specifies the device type and volume serial number of the volume on which the 
catalog search for the data set is to begin. If neither CVOL nor FROM is 
written, the data set is assumed to be cataloged on the system residence 
volume. 


UNCATLG 
specifies that the catalog entry pertaining to the source data set is to be 
removed. This parameter should be used only if the source data set is 
cataloged. UNCATLG is ignored if the volume is identified by FROM. 


CATLG 
specifies that the copied data set is to be cataloged on its receiving volume if 
it is a direct access volume. If a catalog does not exist on the receiving 
volume, a new catalog is created. 


RENAME= name 
specifies that the data set is to be renamed, and indicates the new name. 


FROMDD= ddname 
specifies the name of the DD statement from which DCB and LABEL 
information are obtained. DCB attributes for unloaded data sets are always 
RECFM=FB, LRECL=80, and BLKSIZE=800. This parameter is valid for 
data sets residing on tape volumes. 


TODD= ddname 
specifies the name of a DD statement from.which DCB and LABEL 
information are obtained. This parameter, which is valid for data sets to be 
copies to magnetic tape volumes, describes the mode and label of the magnetic 
tape where the copied data set is to reside. RECFM, LRECL, and BLKSIZE 
information is ignored. 


Note: The source data set, if cataloged, remains cataloged unless UNCATLG is 
specified. 


The FROMDD and TODD parameters can be omitted for 800 bits per inch, 
9-track tape with standard labels on single density units or for 1600 bits per 
inch, 9-track tape with standard labels on dual density units. 


J 


MOVE DSGROUP Statement 


The MOVE DSGROUP statement is used to move groups of data sets that are 
cataloged on the same volume and whose names are partially qualified by one or 

C more identical names. Source data sets are scratched. Data set groups to be 
moved must reside on direct access volumes. 


INCLUDE and EXCLUDE statements, discussed later in this chapter, can be 
used to add to or delete data sets from the group. ‘ 


The format of the MOVE DSGROUP statement is: 


tj ee *e 


where: 


DSGROUP|= name | 
specifies the cataloged data sets to be moved. If name, which is a qualified 
name, is not coded, all data sets cataloged on the specified volume are to be 
moved. If name is coded, all cataloged data sets whose names are qualified 
by this name are moved. If the name is a fully qualified, data set name, only 
that data set is moved. 


TO= device = list 
specifies the volume or volumes to which the specified group of data sets is to 
be moved. 


SS CVOL= device = serial 
specifies the device type and volume serial number of the volume on which the 
catalog search for the data sets is to begin. If CVOL is omitted, the specified 
group of data sets is assumed to be cataloged on the system residence volume. 


PASSWORD 
specifies that password protected data sets contained in the group are to be 
moved. If PASSWORD is omitted, only data sets that are not protected are 
moved. 


UNCATLG 
specifies that the catalog entries pertaining to the specified group of data sets 
are to be removed. 


TODD= ddname 
specifies the name of a DD statement from which DCB and LABEL 
information are obtained. This parameter, which is valid for data set groups to 
be moved to magnetic tape volumes, describes the mode and label of the 
magnetic tape where the moved data sets are to reside. RECFM, LRECL, and 
BLKSIZE information is ignored. TODD can be omitted for 800 bits per inch, 
9-track tape with standard labels on single density units or for 1600 bits per 
inch, 9-track tape with standard labels on dual density units. 


MOVE DSGROUP operations cause the specified catalog to be updated 
automatically unless UNCATLG is specified. 
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COPY DSGROUP Statement 
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The COPY DSGROUP statement is used to copy groups of data sets that are 

cataloged on the same control volume and whose names are partially qualified by 

one or more identical names. Data set groups to be copied must reside on direct 2 
access volumes. 


INCLUDE and EXCLUDE statements, discussed later in this chapter, can be 
used to add data sets to or delete data sets from the data set group to be copied. 
The format of the COPY DSGROUP statement is: 


B54 a 
th oF 


where: 


DSGROUP|[= name | 
specifies the cataloged data sets to be copied. If name, which is a qualified 
name, is not coded, all cataloged data sets on the specified volume are to be 
copied. If name is coded, all cataloged data sets whose names are qualified 
by this name are copied. If the name is a fully-qualified, data set name, only 
that data set is copied. 


TO= device = list 
specifies the volume or volumes on which the specified group of data sets is to 


be copied. } 
CVOL= device = serial 
specifies the device type and volume serial number of the volume on which the 


search for the catalog is to begin. If CVOL is omitted, the specified group of 
data sets is assumed to be cataloged on the system residence volume. 


PASSWORD 
specifies that password-protected data sets contained in the group are to be 
copied. If PASSWORD is omitted, only data sets that are not protected are 
copied. 


UNCATLG 
specifies that the catalog entries pertaining to the source group of data sets are 
to be removed. 


CATLG 
Specifies that the copied data sets are to be cataloged on their receiving 
volumes if they are direct access volumes. If catalogs do not exist on the 
receiving volumes, they are created. 


TODD= ddname 
specifies the name of a DD statement from which DCB and LABEL 
information are obtained. This parameter, which is valid for data set groups to 
be copied to magnetic tape volumes, describes the mode and label of the 
magnetic tape on which the copied data sets are to reside. RECFM, LRECL, 
and BLKSIZE information is ignored. TODD can be omitted for 800 bits per 
inch, 9-track tapes with standard labels on single density units or for 1600 bits 
per inch, 9-track tape with standard labels on dual density units. J 


Note: The source data sets remain cataloged unless UNCATLG is specified. 


MOVE PDS Statement 
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The MOVE PDS statement is used to move partitioned data sets. When used in 
conjunction with INCLUDE, EXCLUDE, REPLACE, or SELECT statements, 
the MOVE PDS statement can be used to merge selected members of several 
partitioned data sets or to delete members. 


If IEHMOVE is used to allocate space for an output partitioned data set, the 
MOVE PDS statement can be used to expand a partitioned directory. 


If the receiving volume contains a partitioned data set with the same name, the 
two data sets are merged. The source data set is scratched. 


The format of the MOVE PDS statement is: 


where: 
PDS= name 
specifies the fully qualified name of the partitioned data set to be moved. 


TO= device = serial 
specifies the device type and volume serial number of the volume to which the 
partitioned data set is to be moved. The /ist parameter may be used when 
unloading a partitioned data set that must span tape volumes. 


FROM2= device = serial 
specifies the device type and volume serial number of the volume on which the 
partitioned data set currently resides, if it is not cataloged. If the data set is 
cataloged, FROM should not be written. FROM=device=list may be used 
when loading a PDS. 


CVOL= device = serial 
specifies the device type and volume serial number of the volume on which the 
catalog search for the partitioned data set is to begin. If neither FROM nor 
CVOL is written, the partitioned data set is assumed to be cataloged on the 
system residence volume. 


EXPAND= nn 
specifies the number of 256-byte records (up to 99 decimal) to be added to 
the directory of the specified partitioned data set. EXPAND cannot be 
specified if space is previously allocated. 


UNCATLG 
specifies that the catalog entry pertaining to the source partitioned data set is 
to be removed. This parameter should be used only if the source data set is 
cataloged. If the volume is identified by FROM, UNCATLG is ignored. 


RENAME= name 
specifies that the data set is to be renamed, and indicates the new name. 
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FROMDD= ddname 
specifies the name of a DD statement from which DCB and LABEL 
information are obtained. This parameter, which is valid for unloaded 
partitioned data sets on tape volumes, describes the mode and label of the x 
magnetic tape and, in addition, must include the DCB attributes of the 2 
unloaded data set (RECFM=FB,LRECL=80,BLKSIZE=800). 


TODD= ddname 
specifies the name of a DD statement from which DCB and LABEL 
information are obtained. This parameter, which is valid for partitioned data 
sets to be unloaded to tape volumes, describes the mode and label of the 
magnetic tape on which the unloaded data set is to reside and, in addition, 
must include the DCB attributes of the unloaded data set 
(RECFM=FB,LRECL=80,BLKSIZE=800). 


The FROMDD and TODD parameters can be omitted for 800 bits per inch, 
9-track tapes with standard labels on single density units or for 1600 bits per 
inch, 9-track tape with standard labels on dual density units. 


Note: MOVE PDS causes the specified catalog to be updated automatically 
unless UNCATLG is specified. 


COPY PDS Statement 


The COPY PDS statement is used to copy partitioned data sets. When used in 
conjunction with INCLUDE, EXCLUDE, REPLACE, or SELECT statements, 
the COPY PDS statement can be used to merge selected members of several 
partitioned data sets or to delete members. 


If IEHMOVE is used to allocate space for an output partitioned data set, the 
COPY PDS statement can be used to expand a partitioned directory. 


If the receiving volume already contains a partitioned data set with the same 
name, the two are merged. wh 


PDS= name 
specifies the fully qualified name of the partitioned data set to be copied. 


TO= device = serial 
specifies the device type and volume serial number of the volume to which the 
partitioned data set is to be moved. The /ist value may be used when 
unloading a partitioned data set that must span tape volumes. 
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FROM2= device = serial 
specifies the device type and volume serial number of the volume on which the 
partitioned data set currently resides, if it is not cataloged. If the data set is 
cataloged, FROM should not be written. FROM=device=list may be used 
when loading a PDS. 


CVOL= device = serial 
specifies the device type and volume serial number of the volume on which the 
catalog search for the partitioned data set is to begin. If neither FROM nor 
CVOL is written, the partitioned data set is assumed to be cataloged on the 
system residence volume. 


EXPAND= nn 
specifies the number of 256-byte records (up to 99 decimal) to be added to 
the directory of the specified partitioned data set. EXPAND cannot be 
specified if space is previously allocated. 


UNCATLG 
specifies that the catalog entry pertaining to the source partitioned data set is 
to be removed. This parameter should be used only if the source partitioned 
data set is cataloged. UNCATLG is ignored if the volume is identified by 
FROM. 


CATLG 
specifies that the copied partitioned data set is to be cataloged on the 
receiving volume if it is a direct access volume. If a catalog does not exist on 
the receiving volume, a new catalog is created. 


RENAME= name 
specifies that the data set is to be renamed, and indicates the new name. 


FROMDD= ddname 
specifies the name of a DD statement from which DCB and LABEL 
information are obtained. This parameter, which is valid for unloaded 
partitioned data sets residing on magnetic tape volumes, describes the mode 
and label of the magnetic tape and, in addition, must include the DCB 
attributes of the unloaded data set 
(RECFM=FB,LRECL=80,BLKSIZE=800). 


TODD= ddname 
specifies the name of a DD statement from which DCB and LABEL 
information are obtained. This parameter, which is valid for partitioned data 
sets to be unloaded to magnetic tape volumes, describes the mode and label of 
the magnetic tape on which the unloaded data set is to reside and, in addition, 
must include the DCB attributes of the unloaded data set 
(RECFM=FB,LRECL=80,BLKSIZE=800). 


The FROMDD and TODD parameters can be omitted for 800 bits per inch, 
9-track tapes with standard labels on single-density units or for 1600 bits per 
inch, 9-track tape with standard labels on dual-density units. 


Note: The source partitioned data set remains cataloged unless UNCATLG is 
specified. 


MOVE CATALOG Statement 


The MOVE CATALOG statement is used to move the entries of a catalog 
without moving the data sets associated with those entries. Certain entries can be 
excluded from the operation by means of the EXCLUDE statement. If the 
receiving volume contains a catalog, the source catalog entries are merged with it. 
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The format of tte MOVE CATALOG statement is: 
[label] asi -CATALOG[= name] — | 
nae device = serial _ | 


a, 
= device = serial) 


where: 


CATALOG|[= name | 
specifies the catalog entries to be moved. If name, which is a fully qualified 
name, is not coded, all entries in the catalog are to be moved. If name is 
coded, all catalog entries whose names are qualified by this name are moved. 
If the name is a fully qualified, data set name, only the catalog entry that 
corresponds to that data set is moved. 


TO= device = serial 
specifies the device type and volume serial number of the volume to which the 
specified catalog entries are to be moved. 


CVOL= device = serial 
specifies the device type and volume serial number of the volume on which the 
search for the catalog is to begin. If both FROM and CVOL are omitted, the 
catalog is assumed to reside on the system residence volume. 


FROM2= device = serial 
specifies the device type and volume serial number of the volume on which an 
unloaded version of the catalog resides. If neither FROM nor CVOL is coded, 
the catalog is assumed to reside on the system residence volume. 


FROMDD= ddname 
specifies the name of a DD statement from which DCB and LABEL 
information are obtained. This parameter, which is valid for unloaded catalogs 
residing on magnetic tape volumes, describes the mode the label of the 
magnetic tape and, in addition, must include the DCB attributes of the 
unloaded catalog (RECFM=FB,LRECL=80, BLKSIZE=800). 


TODD= ddname 
specifies the name of a DD statement from which DCB and LABEL 
information are obtained. This parameter, which is valid for catalogs to be 
unloaded to magnetic tape volumes, describes the mode and label of the 
magnetic tape on which the unloaded catalog is to reside and, in addition, 
must include the DCB attributes of the unloaded catalog 
(RECFM=FB,LRECL=80,BLKSIZE=800). 


The FROMDD and TODD parameters can be omitted for 800 bits per inch, 
9-track tapes with standard labels on single density units or for 1600 bits per 
inch, 9-track tape with standard labels on dual density units. 


The COPY CATALOG statement is used to copy the entries in a catalog 
without copying the data sets associated with these entries. Certain entries can be 
excluded from a copy operation with the EXCLUDE statement. If the receiving 
volume contains a catalog, the source catalog is merged with it. 
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The format of the COPY CATALOG statement is: 


where: 


CATALOG[= name | 
specifies the catalog entries to be copied. If name, which is a fully qualified 
name, is not coded, all entries in the catalog are to be copied. If name is 
coded, all catalog entries whose names are qualified by this name are copied. 
If the name is a fully qualified data set name, only the catalog entry that 
corresponds to that data set is copied. 


TO= device = serial 
specifies the device type and volume serial number of the volume onto which 
the specified catalog entries are to be copied. 


CVOL= device = serial 
specifies the device type and volume serial number of the volume on which the 
search for the catalog is to begin. 


FROM= device = serial 
specifies the device type and volume serial number of the volume on which an 
unloaded version of the catalog resides. If neither FROM nor CVOL is 
written, the catalog is assumed to reside on the system residence volume. 


FROMDD= ddname 
specifies the name of a DD statement from which DCB and LABEL 
information is obtained. This parameter, which is valid for unloaded catalogs 
residing on tape volumes, describes the mode and label of the tape and, in 
addition, must include the DCB attributes of the unloaded catalog 
(RECFM=FB,LRECL=80,BLKSIZE=800). 


TODD= ddname 
specifies the name of a DD statement from which DCB and LABEL 
information are obtained. This parameter, which is valid for catalogs to be 
unloaded onto tape volumes, describes the mode and label of the tape volume 
on which the unloaded catalog is to reside and, in addition, must include the 
DCB attributes of the unloaded catalog 
(RECFM=FB,LRECL=80,BLKSIZE=800). 


The FROMDD and TODD parameters can be omitted for 800 bits per inch, 
9-track tapes with standard labels on single density units or for 1600 bits per 
inch, 9-track tape with standard labels on dual density units. 


MOVE VOLUME Statement 


The MOVE VOLUME statement is used to move all the data sets residing on a 
specified volume. Catalog entries associated with the data sets remain unchanged. 
Data sets to be moved must reside on direct access volumes. 


The format of the MOVE VOLUME statement is: 
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where: 


VOLUME= device = serial 
specifies the device type and volume serial number of the source volume. 


TO= device = list 
specifies the volume or volumes to which the data sets are to be moved. 


PASSWORD 
specifies that password protected data sets are to be included in the operation. 
If PASSWORD is omitted, only data sets that are not protected are moved. 


TODD= ddname 
specifies the name of a DD statement from which DCB and LABEL 
information are obtained. This parameter, which is valid for data sets to be 
moved to tape volumes, describes the mode and label of the receiving tape 
volume. TODD can be omitted for 800 bits per inch, 9-track tapes with 
standard labels on single density units or for 1600 bits per inch, 9-track tape 
with standard labels on dual density units. 


The COPY VOLUME statement is used to copy all the data sets residing on a 
specified volume. Catalog entries associated with the data sets remain unchanged. 
Data sets to be.copied must reside on direct access volumes. 


The format of the COPY VOLUME statement is: 


[ label} COPY VOLUME= device = serial 
TO= device = lisi 
[PASSWORD] 
[CATLG] 
[TODD= ddname | 


where: 


VOLUME2= device = serial 
specifies the device type and volume serial number of the source volume. 


TO= device = list 
specifies the volume or volumes to which the data sets are to be copied. 


PASSWORD 
specifies that password protected data sets are to be included in the operation. 
If PASSWORD is omitted, only data sets that are not protected are copied. 


CATLG 
specifies that all copied data sets are to be cataloged in a SYSCTLG (system 
catalog) data set on the direct access receiving volume. If a catalog does not 
exist on the receiving volume, it is created. 


TODD= ddname 
specifies the name of a DD statement from which DCB and LABEL 
information are obtained. This parameter, which is valid for data sets to be 
copied to magnetic tape volumes, describes the mode and label of the 
receiving magnetic tape volume. TODD can be omitted for 800 bits per inch, 
9-track tapes with standard labels on single-density units or for 1600 bits per 
inch, 9-track tape with standard labels on dual-density units. 


INCLUDE Statement 


If CATLG is specified and the source volume contains a SYSCTLG data set, 
error messages indicating that an inconsistent index structure exists are issued 
when the source SYSCTLG data set entries are merged into the catalog on the 
receiving volume. (Because the SYSCTLG data set is the last to be copied, only 
those entries representing cataloged data sets not residing on the source volume 
are copied into a receiving volume’s SYSCTLG data set; entries representing all 


data sets residing on the source volume have already been made in the receiving 
SYSCTLG data set.) 


The INCLUDE statement is used to enlarge the scope of MOVE DSGROUP, 
COPY DSGROUP, MOVE PDS, or COPY PDS statements by including a 
member or a data set not explicitly defined in those statements. The INCLUDE 
Statement follows the MOVE or COPY statement whose function it modifies. 
Any number of INCLUDE statements can modify a MOVE or COPY statement. 
The INCLUDE statement is invalid when data is unloaded or when unloaded 
data is moved or copied. 


The format of the INCLUDE statement is: 


where: 
DSNAME= name 
specifies the fully qualified name of a data set. When the INCLUDE 
statement modifies a MOVE DSGROUP or COPY DSGROUP statement, the 
named data set is included in the group. When the INCLUDE statement 
modifies a MOVE PDS or COPY PDS statement, either the entire named 
partitioned data set or a member of the data set is included in the operation. 


MEMBER= membername 
specifies the name of a member of the partitioned data set named in the 
DSNAME parameter. This member is merged with the partitioned data set 
that is moved or copied. Its record characteristics must be the same as those 
of the data set with which it it being merged. The data set containing this 
member is not scratched, regardless of the operation. This parameter is valid 
and required only when the INCLUDE statement modifies a MOVE PDS or 
COPY PDS statement. 


FROM2= device = list 
specifies the volume or volumes on which the data set resides, if the data set is 
not cataloged. If the data set is cataloged, FROM should not be specified. If 
both FROM and CVOL are omitted, the specified data set is assumed to be 
cataloged on the system residence volume. 


CVOL= device = serial 
specifies the device type and volume serial number of the volume on which the 
catalog search for the data set is to begin. If both FROM and CVOL are 
omitted, the specified data set is assumed to be cataloged on the system 
residence volume. 
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The EXCLUDE statement is used to restrict the scope of MOVE DSGROUP, 

COPY DSGROUP, MOVE PDS, COPY PDS, MOVE CATALOG, or COPY " 
CATALOG statements by excluding a specific portion of data defined in those J 
statements. 


Partitioned data set members excluded from a MOVE PDS operation cannot be 
recovered (the source data set is scratched). Any number of EXCLUDE 
statements can modify a MOVE PDS or COPY PDS statement. 


Source data sets or catalog entries excluded from a MOVE DSGROUP or 
MOVE CATALOG operation remain available. Only one EXCLUDE statement 
can modify a MOVE DSGROUP, COPY DSGROUP, MOVE CATALOG, or 
COPY CATALOG statement. The EXCLUDE statement is invalid when data is 
unloaded or when unloaded data is moved or copied. 


The format of the EXCLUDE statement is: 


where: 


DSGROUP= name 
specifies a qualified name. If the EXCLUDE statement modifies a MOVE 
DSGROUP or COPY DSGROUP statement, all data sets whose names are 
qualified by this name are excluded from the operation. If the EXCLUDE 
statement modifies a MOVE CATALOG or COPY CATALOG statement, all 
catalog entries whose names are qualified by this name are excluded from the 
operation. 


MEMBER= membername 
identifies a member to be excluded from the partitioned data set being moved wi 
or copied when the EXCLUDE statement modifies a MOVE PDS or COPY 
PDS statement. 


The SELECT statement is used with the MOVE PDS or COPY PDS statement 
to select members to be moved or copied, and to optionally rename these 
members. The SELECT statement cannot be used with either the EXCLUDE or 
REPLACE statement to modify the same MOVE PDS or COPY PDS statement. 
The SELECT statement is invalid when data is unloaded or when unloaded data 
is moved or copied. 


The format of the SELECT statement is: 


where: 


MEMBER=(zame [, name |...) 
identifies the members to be moved or copied. These members belong to the 
partitioned data set identified in the preceding MOVE PDS or COPY PDS 
statement. 


MEMBER=(( name , newname (,,( name,newname )]...) 
identifies the members to be moved or copied and gives the new name for 
each member. 


REPLACE Statement 


The REPLACE statement is used with a MOVE PDS or COPY PDS statement 
to exclude a member from the operation and replace it with a member from 
another partitioned data set. The new member must have the same name as the 
old member and must possess identical record characteristics. Any number of 
REPLACE statements can modify a MOVE PDS or COPY PDS statement. The 
REPLACE statement is invalid when data is unloaded or when unloaded data is 
moved or copied. 


The format of the REPLACE 


statement is: 
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DSNAME= name 
specifies the fully-qualified name of the partitioned data set that contains the 
new member. 


MEMBER= name 
specifies the name of the member. 


FROM= device = serial 
specifies the device type and volume serial number of the volume that contains 
the partitioned data set named in the DSNAME parameter. If the partitioned 
data set is cataloged, FROM should not be specified. 


CVOL= device = serial 
specifies the device type and volume serial number of the control volume on 
which the catalog search for the partitioned data set containing the new 
member is to begin. 


If neither FROM nor CVOL is specified, the partitioned data set is assumed to 
be cataloged on the system residence volume. 


IEHMOVE Examples 


The following examples illustrate some of the uses of IEHMOVE. Table 48 can 
be used as a quick reference guide to IEHMOVE examples. The numbers in the = 
‘‘Example” column point to the examples that follow. 
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Table 48. IEHMOVE Example Directory 


Data Set 
Operation Organization 
MOVE Sequential 
COPY Sequential 
MOVE Data set group 


MOVE PDS Partitioned 


MOVE and Catalog 


CATALOG 

MOVE Catalog 
MOVE Volume 
MOVE Partitioned 
MOVE Partitioned 
MOVE Sequential 
MOVE Sequential 
COPY Sequential 
COPY Partitioned 


Device 


3330 Disk, 
2314 Disks 


3330 Disk, 
2314 or 
2319 Disks! 


2314 Disk, 
3330 Disk, 
2314 Disk 


3330 Disk, 
2314 Disks 


2314 Disk, 
3330 Disk, 
2314 Disk 


3330 Disk, 
2314 Disk 


3330 Disk, 
2314 Disks 


3330 Disk, 
2314 Disks 


3330 Disk, 
2314 Disk 


2314 Disk, 
2400 Tape 


3330 Disk, 
2314 Disk, 
2400 Tape 


2314 Disk, 
2400 Tape 


2400 Tape, 
2314 Disks 


Comments 


Source volume is demounted after 
job completion. Two mountable 
disks. 


Three cataloged sequential data 
sets are to be copied. The 2314 
or 2319 are mountable. 


Data set group is to be moved. The 
2314 disks are mountable. 


A partitioned data set is to be 
moved; a member from another 
PDS is to be merged with it. 


Catalog is to be moved from 
system residence volume to second 
volume. Source catalog is scratched 
from system residence volume. 


Selected catalog entries are to be 
moved from system residence to 
a second volume. SYSCTLG is 
scratched. 


Volume of data sets is to be moved. 


A data set is to be moved to a 
volume on which space was 
previously allocated. 


Three data sets are to be moved 
and unloaded to a volume on which 
space was previously allocated. 


A sequential data set is to be 
unloaded to an unlabeled 9-track 
tape volume. 


Unloaded data sets are to be 
loaded from a single volume. 


Data sets are to be copied from 
Separate source volumes. 


Unloaded data sets are to be 
loaded from non-labeled tape to a 
specific device. 


Example 


[3 


' Note that the 2319 disk is functionally equivalent to the 2314 disk; to use the 2319, specify 
2314 in the control statement. 
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In this example, three data sets (SEQSET1, SEQSET2, and SEQSET3) are to be 
moved from a disk volume to three separate disk volumes. Each of the three 

receiving volumes is mounted when it is required by IEHMOVE. The source data 
sets are not cataloged. Space is allocated by IEHMOVE. 
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IEHMOVE Example 2 


The example follows: 


/ /MOVEDS JOB 09#550,GREEN 

// EXEC PGM=[EHMOVE 

//SYSPRINT DD SYSOUT=A 

YA SLSUL | DD UNIT=3330,VOLUME=SER=333000,DISP=OLD 


L/D DD UNIT T=2314, VOLUME=SER=111111,DISP=OLD 
fF DD2Z DD UNIT=( 2314, ,DEFER),DISP=OLD, 

// VOLUME=( PRIVATE, ,SER=( 231400) ) 

//DD3 DD VOLUME=( PRIVATE, RETAIN, SER=( 231411)), 
// UNIT=2314,DISP=OLD 

f7SLSIN DD * 


MOVE DSNAME=SEQSET 1 , TO=2314=231400, FROM=2314=231411 

MOVE DSNAME=SEQSET2 , TO=2314=231412, FROM=2314=231411 

MOVE DSNAME=SEQSET3 , TO=2314=231413,FROM=2314=231411 
/* 


The control statements are discussed below: 
e SYSUT1 DD defines the device that is to contain the work data set. 
e DD1 DD defines the system residence device. 


e DD2 DD defines the mountable device on which the receiving volumes will be 
mounted as they are required. 


e DD3 DD defines a mountable device on which the source volume is to be 
mounted. Because the RETAIN subparameter is included, the volume remains 
mounted until the job has completed. 


e SYSIN DD defines the control data set, which follows in the input stream. 


e MOVE moves the source data sets to volumes 231400, 231412, and 231413, 
respectively. The source data sets are scratched. 


In this example, three cataloged data sets are to be copied to a 2314 or 2319 
volume. Note that the 2319 is functionally equivalent to the 2314; to use a 2319, 
specify 2314 in the control statement. Space is allocated by IEHMOVE. The 
catalog is not updated. The source data sets are not scratched. 


The example follows: 


J/COPYPDS, JOB: 099550;)GREEN 

IJ EXEC PGM=IEHMOVE 

//SYSPRINT DD SYSOUT=A 

FISYSUTI DD UNIT=2314, VOLUME=SER=231400,DISP=OLD 


FLD DD UNIT=3330,VOLUME=SER=111111,DISP=OLD 
//DD2 DD UNI T=2314, VOLUME=SER=231400,DISP=OLD 
I#DDS DD UNIT=2314, VOLUME=SER=231401,DISP=OLD 


//SYSIN DD * 
COPY DSNAME=SEQSET1 , TO=2314=231401 
COPY DSNAME=SEQSET3 , TO=2314=231401 
COPY DSNAME=SEQSET4 , TO=2314=231401 
/* 


The control statements are discussed below: 

¢ SYSUT1 DD defines the device that is to contain the work data set. 

e DD1 DD defines the system residence device. 

e DD2 DD defines a mountable device on which the source volume is mounted. 


¢ DD3 DD defines a mountable device on which the receiving volume is 
mounted. 


e SYSIN DD defines the control data set which follows in the input stream. 
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¢ COPY copies the source data sets onto volume 231401. 


Note: This example implies that the cataloged source data sets all exist on a 2314 
volume. If the data sets existed on a volume or volumes other than a 2314, the 
necessary DD statements would have to be included in this example to define the 
applicable mountable device(s). 


In this example, the data set group A. B. C—which comprises data sets A.B.C.X, 
A.B.C.Y, and A.B.C.Z—is moved from two 2314 volumes onto a third volume. 
Space is allocated by IEHMOVE. The catalog is updated to refer to the receiving 
volume. The source data sets are scratched. 


The example follows: 


//MOVEDSG JOB 09#550,GREEN 

i EXEC PGM=IEHMOVE 

//SYSPRINT DD SYSOUT=A 

/7SYSUT1 DD UNIT=2314, VOLUME=SER=231401,DISP=OLD 


Ji DDI DD UNIT=3330, VOLUME=SER=111111,DISP=OLD 
//DD2 DD UNIT T=2314, VOLUME=SER=231401,DISP=OLD 
//DD3 DD UNIT=2314, VOLUME=SER=231410,DISP=OLD 
//DD4 DD UNI T=2314, VOLUME=SER=231411,DISP=OLD 
J / SY SIN DD * 


MOVE DSGROUP=A.B.C, TO=2314=231401 
/* 


The control statements are discussed below: 
e SYSUT1 DD defines the device that is to contain the work data set. 
e DD1 DD defines the system residence device. 


¢ DD2 DD defines a mountable device on which the receiving volume is to be 
mounted. 


e DD3 DD defines a mountable device on which one of the source volumes is to 
be mounted. 


e DD4 DD defines a mountable device on which one of the source volumes is to 
be mounted. 


e SYSIN DD defines the control data set, which follows in the input stream. 
« MOVE moves the specified data sets to volume 231401. 


Note: This example can be used to produce the same result without the use of 
the DD4 DD statement, using one less mountable 2314 device. With DD3 and 
DD4, both of the source volumes are mounted at the start of the job. With DD3 
only, the 231410 volume is mounted at the start of the job. After the 231410 
volume is processed, the utility requests that the operator mount the 231411 
volume. In this case the DD3 statement is coded: 


//DD3 DD UNIT=(2314,,DEFER),DISP=OLD, VOLUME=(PRIVATE.,, 
if SER=(231410)) 


In this example, a partitioned data set (PARSET1) is to be moved to a disk 
volume. In addition, a member (PARMEM3) from another partitioned data set 
(PARTSET2) is to be merged with the source members on the receiving volume. 
The source partitioned data set (PARTSET1) is scratched. Space is allocated by 
IEHMOVE. 


a 


9 


IEHMOVE Example 5 


The example follows: 


//MOVEPDS JOB 09#550,GREEN 

iy EXEC PGM=IEHMOVE 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD  UNIT=3330,VOLUME=SER=333000,DISP=OLD 


//DD1 DD UNIT=2314,VOLUME=SER=111111,DISP=OLD 
f/DD2 DD UNIT=2314,VOLUME=SER=231400,DISP=OLD 
//DD3 DD UNIT=2314,VOLUME=SER=231410,DISP=OLD 
//DD4 DD UNIT=2314, VOLUME=SER=231420,DISP=OLD 
//SYSIN DD * 


MOVE PDS=PARTSET 1 , TO=2314=231420, FROM=2314=231400 
INCLUDE DSNAME=PARTSET2 , MEMBER=PARMEM3 , FROM=2314=231410 
/* 


The control statements are discussed below: 
e SYSUT1 DD defines the device that is to contain the work data set. 
e DD1 DD defines the system residence device. 


« The DD2, DD3, and DD4 DD statements define mountable devices that are to 
contain the two source volumes and the receiving volume. 


e SYSIN DD defines the control data set, which follows in the input stream. 


e MOVE defines the source partitioned data set, the volume that contains it, 
and its receiving volume. 


e INCLUDE includes a member from a second partitioned data set in the 
operation. 


In this example, the SYSCTLG data set is to be moved from the system 
residence volume to a mountable 2314 volume. Space is allocated by IEHMOVE. 
The source catalog is scratched from the system residence volume. 


The example follows: 


//MOVECAT1 JOB 09#550,GREEN 

ff EXEC PGM=IEHMOVE 

//SYSPRINT DD SYSOUT=A 

ff SYSUT | DD UNIT=2314, VOLUME=SER=231400,DISP=OLD 


//DD1 DD UNIT=3330, VOLUME=SER=111111,DISP=OLD 
7 /DD2 DD UNIT=2314,VOLUME=SER=222222,DISP=OLD 
JI SYSLN DD = 


MOVE CATALOG , TO=2314=222222 
/* 


The control statements are discussed below: 
« SYSUTI1 DD defines the device that is to contain the work data set: 


¢« DD1 DD defines the system residence device. The system residence volume 
contains the catalog to be moved. 


e DD2 DD defines the mountable device on which the receiving volume is to be 
mounted. 


e SYSIN DD defines the control data set, which follows in the input stream. 


e MOVE specifies the move operation and defines the receiving volume. 
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In this example, the data set group A.B.C—which comprises data sets entries 
A.B.C.X, A.B.C.Y, and A.B.C.Z—is to be moved from the SYSCTLG data set 
to a mountable 2314 volume. If no catalog exists on the 2314 volume, one is 
created; if a catalog does exist, the specified entries are merged into it. The 
source SYSCTLG data set is scratched. The work data set is deleted when the 
job step is completed. 


The example follows: 


//MOVECAT2 JOB 09#550,GREEN 

aa EXEC PGM=IEHMOVE 

J//SVSPRINY DD SYSOUT=A 

7 /SYSUT] DD UNI T=2314, VOLUME=SER=231402,DISP=OLD 


//DD1 DD UNIT=3330, VOLUME=SER=111111,DISP=OLD 
//DD2 DD UNTT=2314, VOLUME=SER=231402,DISP=OLD 
JP SLSIN DD * 


MOVE CATALOG=A.B.C, TO=2314=231402 
/* 


The control statements are discussed below: 


e SYSUTI1 DD defines the device that is to contain the work data set. (Because 
IEHMOVE deletes the work data set at the completion of the program, it can 
be contained on the receiving volume, provided there is room for it.) 


« DD1 DD defines the system residence device. The system residence volume 
contains the entries to be moved. 


e DD2 DD defines the mountable device on which the receiving volume is to be 
mounted. 


e SYSIN DD defines the control data set, which follows in the input stream. 


e MOVE specifies a move operation for selected entries and defines the 
receiving volume. 


In this example, a volume of data sets is to be moved to a 2314 volume. All data 
sets that are successfully moved are scratched from the source volume; however, 
any catalog entries pertaining to those data sets are not changed. Space is 
allocated by IEHMOVE. The work data set is deleted when the job step is 
completed. 


The example follows: 


//MOVEVOL JOB 09#550,GREEN 
EXEC PGM=IEHMOVE 
//SYSPRINT DD  SYSOUT=A 
//SYSUT1 DD  UNIT=2314, VOLUME=SER=231400,DISP=OLD 


Jf DD: DD UNIT=3330,VOLUME=SER=111111,DISP=OLD 
7 /DD2 DD UNI T=2314, VOLUME=SER=231400,DISP=OLD 
//DD3 DD UNI T=2314,VOLUME=SER=231401,DISP=OLD 
LPOLoOLN DD * 


MOVE VOLUME=2314=231401 , TO=2314=231400, PASSWORD 
/* 


The control statements are discussed below: 


¢ SYSUT1 DD defines the device that is to contain the work data set. The work 
data set is removed from the receiving volume when the job step is completed. 


e DD1 DD defines the system residence device. 


e DD2 DD defines the mountable device on which the receiving volume is to be 
mounted. 


J 
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« DD3 DD defines a mountable device on which the source volume is to be 
mounted. 


e SYSIN DD defines the control data set, which follows in the input stream. 


e MOVE specifies a move operation for a volume of data sets and defines the 
source and receiving volumes. This statement also indicates that 
password-protected data sets are to be included in the operation. 


Note: IEHPROGM can be used to uncatalog catalog entries pertaining to source 
data sets and to catalog the moved versions of those data sets. 


In this example, a partitioned data set is to be moved to a 2314 volume on which 
Space has been previously allocated for the data set. The source data set is 
scratched. The work data set is deleted when the job step is completed. 


The example follows: 


//ALLOCATE JOB 09#550,GREEN 


fej EXEC PGM=IEHPROGM 
i PSLSPRINT- DD SYSOUT=A 
Fi SEDI DD DSNAME=PDSSET1,UNIT=2314,DISP=(NEW,KEEP ), 


// VOLUME=SER=231401,SPACE=(TRK,(100,10,10)), 
// DCB=( RECFM=FB,LRECL=80, BLKSIZE=2000 ) 


//SYSIN DD ¥ 
/* 
// EXEC PGM=IEHMOVE 


7 /SYSPRINT “DD SYSOUT=A 
7 {SLSUT) DD UNIT=2314,VOLUME=SER=231401,DISP=OLD 


//DD1 DD  UNIT=3330,VOLUME=SER=111111,DISP=OLD 
//DD2 DD UNIT=2314,VOLUME=SER=231401,DISP=OLD 
//DD3 DD UNIT=2314, VOLUME=SER=231402,DISP=OLD 
//SYSIN DD x 


MOVE PDS=PDSSET1 , TO=2314=231401,FROM=2314=231402 
/* 
The IEHPROGM job step is used to allocate space for data set PDSSET1 on a 
2314 volume. 


The control statements are discussed below: 


¢ SYSUT1 DD defines the device that is to contain the work data set. The data 
set is removed from the receiving volume at the completion of the program. 


e DD1 DD defines the system residence device. 
« DD2 DD defines the device on which the receiving volume is to be mounted. 


e DD3 DD defines a mountable device on which the source volume is to be 
mounted. 


¢ SYSIN DD defines the control data set, which follows in the input stream. 


« MOVE specifies a move operation for the partitioned data set PDSSET1 and 
defines the source and receiving volumes. 


In this example, three partitioned data sets are to be moved from three separate 
source volumes to a 2314 volume. The source data set PDSSET3 is unloaded. 
(The record size exceeds the track capacity of the receiving volume.) The work 
data set is deleted when the job step is completed. 
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The example follows: 


//ALLOCATE JOB 09#550,GREEN 

// EXEC PGM=IEHPROGM 

//SYSPRINT DD  SYSOUT=A 

//SET1 DD DSNAME=PDSSET1,UNIT=2314,DISP=(NEW,KEEP), Jo 
// VOLUME=SER=231401,SPACE=( TRK,(50,10,5)), 

// DCB=( RECFM=FB, LRECL=80, BLKSIZE=1600 ) 

//SET2 DD  DSNAME=PDSSET2,UNIT=2314,DISP=( NEW,KEEP ), 
// VOLUME=SER=231401,SPACE=( TRK,(25,5,5)), 

// DCB=( RECFM=F, LRECL=80,BLKSIZE=80 ) 

//SET3 DD DSNAME=PDSSET3,UNIT=2314,DISP=(NEW,KEEP), 
// NOLUME=SER=231401,SPACE=(TRK,(25,5)), 

// DCB=( RECFM=U, BLKSIZE=5000 ) 

//SYSIN DD * 

/* 

Tit EXEC PGM=IEHMOVE 

//SYSPRINT DD  SYSOUT=A 

//SYSUT1 DD  UNIT=2314, VOLUME=SER=231401,DISP=OLD 


70D DD UNTT=3330, VOLUME=SER=111111,DISP=OLD 
//DD2 DD UNIT=(2314,,DEFER),DISP=OLD, 

df VOLUME=( PRIVATE, , SER=( 231400) ) 

//DD3 DD UNIT=2314, VOLUME=SER=231401,DISP=OLD 


f//S5YSIN DD * 
MOVE PDS=PDSSET1 , TO=23 14=23 1401, FROM=2314=231400 
MOVE PDS=PDSSET2 , TO=23 14=231401,FROM=2314=231401 
MOVE PDS=PDSSET3 , TO=23 14=231401,FROM=2314=231402 
/* 
The IEHPROGM job step is used to allocate space for the partitioned data sets 
PDSSET1, PDSSET2, and PDSSET3 on the receiving volume. The SPACE 
parameter in the SET3 DD statement allocates space for a sequential data set. 
This is necessary to successfully unload the partitioned data set PDSSET3. The 
DCB attributes of PDSSET3 are: 


DCB=(RECFM=U,BLKSIZE=5000) 


The unloaded attributes are: 
DCB=(RECFM=FB,LRECL=80,BLKSIZE=800) 

The control statements are discussed below: 

e SYSUT1 DD defines the device that is to contain the work data set. 

e DD1 DD defines the system residence device. 


« DD2 DD defines a mountable device on which the source volumes are 
mounted as they are required. 


e DD3 DD defines a mountable device on which the receiving volume is 
mounted. 


e SYSIN DD defines the control data set, which follows in the input stream. 


e MOVE specifies move operations for the partitioned data sets and defines the 
source and receiving volumes. 


Note: For a discussion on estimating space allocations, refer to OS/VS Data 
Management Services Guide, GC26-3783. 


In this example, a sequential data set is to be unloaded onto a 9-track, unlabeled 
tape volume (800 bits per inch). The work data set resides on the source volume 
and is deleted when the job step is completed. 


C 
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The example follows: 


7 

//UNLOAD JOB 09#550,GREEN 
Ti EXEC PGM=IEHMOVE 
//SYSPRINT DD  SYSOUT=A 
//SYSUT1 DD  UNIT=2314, VOLUME=SER=231400,DISP=OLD 
//DD1 DD UNIT=2314, VOLUME=SER=111111,DISP=OLD 
//DD2 DD UNIT=2314, VOLUME=SER=231400,DISP=OLD 
//TRPEOUT DD  UNIT=2400, VOLUME=SER=SCRTCH, DISP=OLD, 
// DCB=( DEN=2,RECFM=FB, LRECL=80 , BLKSIZE=800 ), 
// LABEL=( ,NL) 
//SYSIN DD * 

MOVE  DSNAME=SEQSET1,TO=2400=SCRTCH, VAC 


FROM=2314=231400, TODD=TAPEOUT 
/ * 


The control statements are discussed below: 

e SYSUT1 DD defines the device that is to contain the work data set. 

e DD1 DD defines the system residence device. 

e DD2 DD defines a mountable device on which the source volume is mounted. 


e TAPEOUT DD defines a mountable device on which the receiving tape 
volume is mounted. This statement also provides label and mode information. 


e SYSIN DD defines the control data set which follows in the input stream. 


e MOVE moves the sequential data set SEQSET1 from a 2314 volume to the 
receiving tape volume. The data set is unloaded. The TODD parameter in this 
statement refers to the TAPEOUT DD statement for label and mode 
information. 


In this example, three unloaded sequential data sets are to be loaded from a 
labeled, 7-track tape volume (556 bits per inch) to a 2314 volume. Space is 
allocated by IEHMOVE. The example assumes that the 2314 volume is capable 
of supporting the data sets in their original forms. 


The example follows: 


72 
//LOAD JOB 09#550,GREEN 
Ve EXEC PGM=IEHMOVE 
//SYSPRINT DD  SYSOUT=A 
//SYSUT1 DD  UNIT=2314, VOLUME=SER=231400,DISP=OLD 
//DD1 DD  UNIT=3330, VOLUME=SER=111111,DISP=OLD 
//DD2 DD UNIT=2314, VOLUME=SER=231400,DISP=OLD 
//TAPESETS DD DSNAME=UNLDSET1,UNIT=2400-2, 
// NOLUME=SER=001234,DISP=OLD, 
// LABEL=(1,$L),DCB=( DEN=1,TRTCH=C ) 
//SYSIN DD * 
MOVE  DSNAME=UNLDSET1,T0=2314=231400, Vc 
FROM=2400-2=( 001234, 1),FROMDD=TAPESETS 
MOVE DSNAME=UNLDSET2,TO=2314=231400, ‘ic 


FROM=2400-2=( 001234,2),FROMDD=TAPESETS 
MOVE DSNAME=UNLDSET3 , TO=2314=231400, 
FROM=2400-2=( 001234,3),FROMDD=TAPESETS 


/* 
The control statements are discussed below: 


« SYSUTI1 DD defines the device that is to contain the work data set. 


e DD1 DD defines the-system residence device. 
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e DD2 DD defines a mountable device on which the receiving volume is 
mounted. 


e TAPESETS DD defines a mountable device on which the source volume is 
mounted. DCB information is provided in this statement. 


e SYSIN DD defines the control data set, which follows in the input stream. 
¢ MOVE moves the unloaded data sets to the receiving volume. 


Note: To move a data set from a tape volume that contains more than one data 
set, you must specify the sequence number of the data set in the /ist field of the 
FROM or TO parameter on the utility control statement. 


In this example, two sequential data sets are to be copied from separate source 
volumes to a 2314 volume. Space is allocated by IEHMOVE. Only one 9-track 
tape unit is available for the operation. 


The example follows: 


72 
//DEFER JOB 09#550,GREEN 
df EXEC PGM=IEHMOVE 
//SYSPRINT DD SYSOUT=A 
//SYSUT1 DD  UNIT=2314,VOLUME=SER=231400,DISP=OLD 
//DD1 DD UNIT=2314, VOLUME=SER=111111,DISP=OLD 
//DD2 DD UNIT=2314, VOLUME=SER=231400,DISP=OLD 
//TRPE1 DD DSNAME=SEQSET1,UNIT=2400,DISP=OLD, 
// LABEL=(2,SL),VOLUME=SER=001234, 
// DCB=( DEN=2,RECFM=U, BLKSIZE=2000 ) 
//TAPE2 DD DSNAME=SEQSET9, UNIT=AFF=TAPE1,DISP=OLD, 
// LABEL=(4,SL), VOLUME=SER=001235, 
// DCB=( DEN=2,RECFM=FB, LRECL=80 , BLKSIZE=400 ) 
//SYSIN DD 
COPY DSNAME=SEQSET1, TO=2314=231400, A Vic 
FROM=2400=(001234,2),FROMDD=TAPE1 
COPY DSNAME=SEQSET9, TO=2314=231400, “Vc 


FROM=2400=(001235,4 ), FROMDD=TAPE2 
/* 


The control statements are discussed below: 
e SYSUT1 DD defines the volume that is to contain the work data set. 
e DD1 DD defines the system residence device. 


e DD2 DD defines a mountable device on which the receiving volume is 
mounted. 


« TAPEI1 DD defines a mountable device on which the first volume to be 
processed is mounted. The source data set is the second data set on the 
volume. 


« TAPE2 DD defines a mountable device on which the second volume to be 
processed is mounted when it is required. The source data set is the fourth 
data set on the volume. 


e SYSIN DD defines the control data set, which follows in the input stream. 
e COPY copies the data sets to the receiving volume. 


Note: To copy a data set from a tape volume that contains more than one data 
set, you must specify the sequence number of the data set in the list field of the 
FROM or TO parameter on the utility control statement. 
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In 


this example, three unloaded partitioned data sets residing on a non-labeled 


tape volume mounted on device 282 are copied to a 2314 volume mounted on 
device 191. 


The example follows: 


7 F\2ORD 

if 
//SYSPRINT 
//SYSABEND 
//SYSUT1 
//DD1 
//TAPE1 

// LABEL=( 
//SYSIN 


JOB MEDDAUGH, PS40300439,MSGLEVEL=1 

EXEC PGM=IEHMOVE 

DD SYSOUT=A 

DD or sOUT=A 

DD UNIT=191 , VOLUME=SER=231400,DISP=OLD 
DD UNIT=191,VOLUME=SER=231400,DISP=OLD 
DD UNIT=282 , VOLUME=SER=NLTAPE,DISP=OLD, 


/NL) 


DD ** 


COPY PDS=DSET1,FROM=282=(NLTAPE,1),TO=191=231400, FROMDD=TAPE1 
COPY PDS=DSET2, FROM=282=(NLTAPE, 2 ), TO=191=231400,FROMDD=TAPE1 
COPY PDS=DSET3, FROM=282=( NLTAPE, 3 ),TO=191=231400, FROMDD=TAPE1 


/* 


The control statements are discussed below: 


SYSUT1 DD defines the work data set. 


TAPEI! DD defines the source data sets. They are, in the order in which they 
reside on the volume, DSET1, DSET2, and DSET3. 


DD1 DD defines the receiving volume. 
SYSIN DD defines the control data set, which follows in the input stream. 


COPY copies the unloaded partitioned data sets from the non-labeled tape to 
the receiving volume. 


Note: To copy data sets from a non-labeled tape, you must place a label in the 
list field of the FROM parameter of the utility control statement. Following this 
label, the sequence numbers of the data sets must also be included in the same 
field. The unit address must appear in the device field of the FROM or TO 
parameter whenever you want to move from or copy to a specific device. 
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IEHPROGM Program 


IEHPROGM is a system utility used to modify system control data and to 
maintain data sets at an organizational level. (See “Introduction” for general 
system utility information.) IEHPROGM can only be used by those programmers 
locally authorized to do so. 


IEHPROGM can be used to: 

e Scratch a data set or a member. 

e Rename a data set or a member. 

e Catalog or uncatalog a data set. 

e Build or delete an index or an index alias. 

e Connect or release two volumes. 

e Build and maintain a generation-data-group index. 

e Maintain data set passwords. | 

At the completion or termination of the program, the highest return code 


encountered within the program is passed to the calling program. 


Scratching a Data Set or Member 


TEHPROGM can be used to scratch the following from a direct access volume or 
volumes: 


¢ Sequential, indexed sequential, partitioned, or direct access data sets. 
e Members of a partitioned data set. 

e Password-protected data sets. 

¢« Data sets named by the operating system. 


A data set is considered scratched when its data set control block is removed 
from the volume table of contents (VTOC) of the volume on which it resides; its 
space is made available for reallocation. 


The space occupied by a data set residing on a device that operates in 
split-cylinder mode is not available for reallocation until all data sets sharing the 
cylinder have been scratched. 


A member is considered scratched when its name is removed from the directory 
of the partitioned data set in which it is contained. The space occupied by a 
scratched member is not available for reallocation until the partitioned data set is 
scratched or compressed. (When scratching a member of a partitioned data set, 
all aliases of that member should also be removed from the directory.) 


Renaming a Data Set or Member 


IEHPROGM can be used to rename a data set or member that resides on a 
direct access volume. In addition, the program can be used to change any 
member aliases. 
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IEHPROGM can be used to catalog or uncatalog a sequential, 
indexed-sequential, partitioned, or data set accessed by using BDAM. A data set 
is cataloged when its fully-qualified name and volume identification are entered 
in One or more index levels of the SYSCTLG data set. The program catalogs a 
data set by generating an entry, containing the data set name and associated 
volume information, in the index of the catalog. If higher level indexes are 
necessary to catalog the data set, they are automatically created. 


The catalog function is used to: (1) catalog a data set that was not cataloged 
when it was created, or (2) satisfy, if necessary, the requirement that a 

higher level index or indexes be created. Figure 56 shows how data set A.F.G is 
cataloged on the system residence volume. Note that the level F index does not 
exist in the SYSCTLG data set before the catalog operation. 


System residence— System residence— 
before cataloging A.F.G. after cataloging A.F.G. 


aa To 


SYSCTLG 
data set 


Figure 56. Cataloging a Data Set Using IEHPROGM 


The catalog function of IEHPROGM differs from a DISP=(,CATLG) 
specification in a DD statement in that the DISP=(,CATLG) specification 
cannot create higher level indexes and cannot catalog a data set on a volume 
other than the system residence volume unless the system residence volume is 
properly connected to the other volume. (Refer to “Connecting or Releasing 
Two Volumes’’ in this chapter for a discussion of connected volumes.) 


IEHPROGM uncatalogs a data set by removing the data set name and associated 
volume information from the lowest level index of the catalog. 


The uncatalog function of the program differs from a DISP=(....UNCATLG) 
specification in a DD statement in that the DISP=(....UNCATLG) specification 
cannot remove an entry from the SYSCTLG data set on a volume other than the 
system residence volume unless the two volumes are properly connected. 


Figure 57 shows how data set A.F.G is uncataloged by the program. Prior to the 
operation, the fully qualified name and associated volume information are 
represented in the catalog. The uncatalog operation removes the lowest level 
entry from the index structure. Note that the structure A.F remains in the 
catalog. 


System residence— System residence— 
prior to uncataloging A.F.G. after uncataloging A.F.G. 


To 
SYSCTLG 
data set 


Figure 57. Uncataloging a Data Set Using IEHPROGM 


Building or Deleting an Index 


IEHPROGM can be used to build a new index in the catalog or to delete an 
existing index. In building an index, the program automatically creates as many 
higher level indexes as are necessary to complete the specified structure. 


IEHPROGM can be used to delete one or more indexes from an index structure; 
however, an index cannot be deleted if it contains any entries. That is, it cannot 
be deleted if it refers to a lower level index or if it is part of a structure 
indicating the fully-qualified name of a cataloged data set. 


Figure 58 shows an index structure before and after a build operation. The 
left-hand portion of the figure shows two cataloged data sets, A.Y.YY and 
A.B.X.XX, before the build operation. The right-hand portion of the figure 
shows the index structure after the build operation, which was used to build 
index A.B.C.D.E. Note in the left-hand portion of the figure that index levels C 
and D do not exist before the build operation. These levels are automatically 
created when the level E index is built. 


A A 
B B 
Y Y 
x 
YY 
VY x 
XX 


Before build operation After build operation 


Figure 58. Index Structure Before and After an IEHPROGM Build Operation 
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When the level E index is subsequently deleted, the level C and D indexes are 
not automatically deleted by the program. To delete these index levels, delete: 
A.B.C.D.E, A.B.C.D, and A.B.C, in that order. The level B index cannot be 
deleted because data set A.B.X.XX and the X level index are dependent upon 
the level B index. 


Building or Deleting an Index Alias 


IEHPROGM can be used to assign an alternative name (alias) to the 
highest level index of a catalog or to delete an alias previously assigned. An alias 
cannot, however, be assigned to the highest level of a generation index. 


Figure 59 shows an alias, XX, that is assigned to index A (a high level index). 
The cataloged data set A.B.C can be referred to as either A.B.C or XX.B.C. 


To 
SYSCTLG 
data set 


Figure 59. Building an Index Alias Using IEHPROGM 


Connecting or Releasing Two Volumes 
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IEHPROGHM can be used to connect a volume to a second volume by placing an 
entry into a high level index on the first volume. The entry contains an index 
name and the volume serial number and device type of the second volume. The 
program can subsequently release the volumes by removing the entry from the 
high level index. If two volumes are connected: 


e The catalog (SYSCTLG data set) must be created on the second volume for 
cataloging of data sets having the same high level index as the connected 
index. 


e Normal JCL can be used to process (catalog, retrieve, uncatalog) data sets 
cataloged on the second volume, if the high level index has been connected 
from the first volume. 


e A high level index can only be connected to one second volume, but chaining 
is possible from a second to a third volume, etc. 


If the SYSCTLG data set is extended to a second volume, it must be identified 
on that volume. 


Figure 60 shows how the system residence volume can be connected to a second 
volume. Any subsequent index search for index X on the system residence 
volume is carried to the second volume. 


System residence volume Connected volume 


To 
SYSCTLG 
data set data set 


Device type 
and serial 
number of 
connected 
volume 


Figure 60. Connecting a Volume to a Second Volume Using IEHPROGM 


Note: The index name of each high level index existing on the second volume 
must be present in the first volume; when a new high level index is placed on a 
second volume, the first volume should be connected to the second volume. 


Figure 61 shows three volumes connected to the system residence volume. All 
volumes are accessible (through high level indexes X, Y, and Z) to the operating 
system. 


System residence System residence 


Volume 2 Volume 4 


Figure 61. Connecting Three Volumes Using IEHPROGM 


Building and Maintaining a Generation-Data-Group Index _ 


IEHPROGM can be used to build an index structure for a generation data group 
and to control the action to be taken should the index overflow. 


The lowest level index in the structure can contain up to 255 entries for 
successive generations of a data set. If the index overflows, the oldest entry is 
removed from the index, unless otherwise specified (in which case all entries are 
removed). If desired, the program can be used to scratch all generation data sets 
whose entries are removed from the index. 


Figure 62 shows the index structure created for generation data group A.B.C. In 
this example, provision is made for up to five subsequent entries in the 
lowest level index. 
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Figure 62. Building a Generation-Data-Group Index Using IEHPROGM 


Note: Before a generation data group can be cataloged as such, a 
generation-data-group index must exist. Otherwise, a generation data set is 
cataloged as an individual data set, rather than as a generation. 


When creating and cataloging a generation data set, the user can provide 
necessary DCB information. See ‘Providing DCB Attributes” in ‘Appendix D: 
Generation Data Groups” for a discussion of how DCB attributes are provided 
for a generation data group. 


Maintaining Data Set Passwords 
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IEHPROGM can be used to maintain password entries in the PASSWORD data 
set and to alter the protection status of direct access data sets in the data set 
control block (DSCB). For a complete description of data set passwords and the 
PASSWORD data set, see OS/VS Data Management for System 
Programmers , Order Number GC28-0631, and OS/VS Data Management 
Services Guide , GC26-3783. 


A data set can have one of three types of password protection, as indicated in 
the DSCB for direct access data sets and in the tape label for tape data sets (see 
OS/VS1 System Data Areas , SY28-0605, or OS/VS2 System Data Areas, 
SY28-0606, for a description of the DSCB and tape label). The possible types of 
data set password protection are: 


e No protection, which means that no passwords are required to read or write 
the data set. 


¢ Read/write protection, which means that a password is required to read or 
write the data set. 


e Read-without-password protection, which means that a password is required 
only to write the data set; the data set can be read without a password. 


Note: If a system data set is password protected and a problem occurs on a 
system data set, maintenance personnel must be provided with the password in 
order to access the data set and resolve the problem. 


A data set can have one or more passwords assigned to it; each password has an 
entry in the PASSWORD data set. A password assigned to a data set can allow 
read and write access or only read access to the data set. 


Figure 63 shows the relationship between the protection status of data set ABC 
and the type of access allowed by the passwords assigned to the data set. 
Passwords ABLE and BAKER are assigned to data set ABC. If no password 
protection is set in the DSCB or tape label, data set ABC can be read or written 
without a password. If read/write protection is set in the DSCB or tape label, 
data set ABC can be read with either password ABLE or BAKER and can be 
written with password ABLE. If read-without-password protection is set in the 
DSCB or tape label, data set ABC can be read without a password and can be 
written with password ABLE; password BAKER is never needed. 
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Figure 63. Relationship Between the Protection Status of a Data Set and Its 
Passwords 


Before IEHPROGM is used to maintain data set passwords, the PASSWORD 
data set must reside on the system residence volume. IEHPROGM can then be 
used to: 


e Add an entry to the PASSWORD data set. 

e Replace an entry in the PASSWORD data set. 

e Delete an entry from the PASSWORD data set. 

e Provide a list of information from an entry in the PASSWORD data set. 


Each entry in the PASSWORD data set contains the name of the protected data 
set, the password, the protection mode of the password, an access counter, and 
77 bytes of optional user data. The protection mode of the password defines the 
type of access allowed by the password and whether the password is a control 
password or secondary password. The initial password added to the PASSWORD 
data set, for a particular data set, is marked in the entry as the control password 
for that data set. The second and subsequent passwords added for the same data 
set are marked as secondary passwords. 


For direct access data sets, IEHPROGM updates the protection status in the 
DSCB when a control password entry is added, replaced, or deleted. This permits 
setting and resetting the protection status of an existing direct access data set at 
the same time its passwords are added, replaced, or deleted. IEHPROGM 
automatically alters the protection status of a data set in the DSCB if the 
following conditions are met: 


e The control password for the data set is being added, replaced, or deleted. 
e The data set is online. 


e The volume on which the data set resides is specified on the utility control 
statement, or the data set is cataloged. 
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Adding Data Set Passwords 


¢ The data set is not allocated within the IEHPROGM job. 


For tape data sets, IEHPROGM cannot update the protection status in the tape 
label when a password entry is added, replaced, or deleted. Protection status in a 
tape label must be set with JCL. 


Passwords to be added, replaced, deleted, or listed can be specified on utility 
control statements or can be entered by the console operator. IEHPROGM issues 
a message to the console operator when a password on a utility control statement 
is either missing or invalid. The message contains the job name, step name, and 
utility control statement name and identifies the particular password that is 
missing or invalid. Two invalid passwords are. allowed per password entry on 
each utility control statement before the request is ignored; a total of five invalid 
passwords is allowed for the password entries on all the utility control statements 
in a job step before the step is canceled. 


When a password is added for a data set, an entry is created in the PASSWORD 
data set with the specified data set name, password name, protection mode of the 
password (read/write or read-only), and the optional 77 characters of 
user-supplied data. The access counter in the entry is set to zero. 


The control password for a data set must always be specified to add, replace, or 
delete secondary passwords. The control password should not be specified, 
however, to list information from a secondary password entry. 


Secondary passwords can be assigned to a data set to restrict some users to 
reading the data set or to record the number of times certain users access the 
data set. The access counter in each password entry provides a count of the 
number of times the password was used to successfully open the data set. 


If a control password for a direct access, online data set is added, the protection 
status of the data set (read/write or read-without-password) is set in the DSCB. 
However, the data set to be protected must not be allocated within the same job 
as the one in which IEHPROGM is executed. If it is allocated, the DSCB cannot 
be accessed and the protection status is not set. If the data set to be protected is 
being created within the same job, use JCL to set the protection status in the 
DSCB. 


Replacing Data Set Passwords 


Any of the following information may be replaced in a password entry: the 
password, protection mode (read/write or read-only) of the password, and the 
77 characters of user data. The access counter of the password entry is set to 
zero when any information in the entry is replaced. The protection status of a 
data set can be changed by replacing the control entry for the data set. 


If the control entry of a direct access, online data set is replaced, the DSCB is 
also reset to indicate any change in the protection status of the data set. 
Therefore, the user should ensure that the volume is online when changing the 
protection status of a direct access data set. 


Deleting Data Set Passwords 
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When a control password entry is deleted from the PASSWORD data set, all 
secondary password entries for that data set are also deleted. However, when a 
secondary entry is deleted, no other password entries are deleted. 


J 


2 


C 


Listing Password Entries 


Input and Output 


If the control password entry is deleted for an online, direct access data set, the 
protection status of the data set in the DSCB is also changed to indicate no 
protection. When deleting a control password for a direct access data set, the 
user should ensure that the volume is online. If the volume is not online, the 
password entry is removed, but data set protection is still indicated in the DSCB; 
the data set cannot be accessed unless another password is added for that data 
set. 


If the control password entry is deleted for a tape data set, the user must change 
the protection status in the tape label to indicate no protection; otherwise, the 
data set cannot be accessed. The tape label may be changed using the IEHINITT 
utility program. 


The delete function should be used to delete all the password entries for a 
scratched data set to make the space available for new entries. 


A list of information from any entry in the PASSWORD data set can be 
obtained in the SYSPRINT data set by providing the password for that entry. 
The list includes: the number of times the password has been used to successfully 
open the data set; the type of password (control password or secondary 
password) and type of access allowed by the password (read/write or read-only); 
and the user data in the entry. Figure 64 shows a sample list of information 
printed from a password entry. 


DECIMAL ACCESS COUNT= 000025 
PROTECT MODE: -BYTE= SECONDARY, READ ‘ONLY 
USER DATA FIELD= ASSIGNED TO J. BROWN 


Figure 64. Listing of a Password Entry 


IEHPROGM uses as input a control data set that contains utility control 
statements used to control the functions of the program and to indicate those 
data sets or volumes that are to be modified. 


IEHPROGM produces as output a modified object data set or volume(s) and a 
message data set, which contains any error messages and information from the 
PASSWORD data set. 


IEHPROGM provides a return code to indicate the results of program execution. 
The return codes and their meanings are: 


¢ OO, which indicates successful completion. 


¢ 04, which indicates that a syntax error was found in the name field of the 
control statement or in the PARM field in the EXEC statement. Processing is 
continued. 


e 08, which indicates that a request for a specific operation was ignored because 
of an invalid control statement or an otherwise invalid request. The operation is 
not performed. 


e 12, which indicates that an input/output error was detected when trying to 
read from or write to SYSPRINT, SYSIN or the VTOC. 


e 16, which indicates an unrecoverable error. The job step is terminated. 
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Control 


Job Control Statements 
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IEHPROGM is controlled by job control statements and utility control 
Statements. 


Job control statements are used to: ; 
e Execute or invoke the program. 
e Define the control data set. 


¢ Define volumes and/or devices to be used during the course of program 
execution. 


¢ Prevent data sets from being deleted inadvertently. 


e Prevent volumes from being demounted before they have been completely 
processed by the program. 


e Suppress listing of ‘utility control statements. 


Utility control statements are used to control the functions of the program and to 
define those data sets or volumes that are to be modified. 


Table 49 shows the job control statements necessary for using IEHPROGM. 


Table 49. TIEHPROGM Job Control Statements 


Statement Use 
JOB Initiates the job. 
EXEC Specifies the program name (PGM=IEHPROGM) or, if the job control 


statements reside in a procedure library, the procedure name. Additional 

PARM information can be specified to control the number of lines per page 
on the output listing and to suppress printing of utility control statements. 
See ““PARM Information on the EXEC Statement”’ below. , 


SYSPRINT DD _ Defines a sequential message data set. 


anynamel DD Defines a permanently mounted volume. (The system residence volume is 
considered to be a permanently mounted volume.) 

anyname2 DD Defines a mountable device type. 

SYSIN DD Defines the control data set. The control data set normally follows the job 


control statements in the input stream; however, it can be defined as a 
member of a procedure library. 


The anynamel DD statement can be entered: 
//anynamel DD UNIT=xxxx, VOLUME=SER=xxxxxx, DISP=OLD 


The UNIT and VOLUME parameters define the device type and volume serial 
number. The DISP=OLD specification prevents the inadvertent deletion of a 


data set. The anynamel DD statement is arbitrarily assigned the ddname DD1 in 
the IEHPROGM examples. 


The anyname2 DD statement can be coded in the following ways: 
//anyname2 DD VOLUME=SER=xxxxxx,UNIT=xxxx, DISP=OLD 


//anyname2 DD VOLUME=(PRIVATE,SER=xxxxxx), 
res UNIT =(xxxx,, DEFER), DISP=OLD 


The second example can be used to specify deferred mounting when a large 
number of magnetic tapes or direct access volumes. are to be processed in one 
application of the program. The anyname2 DD statement is arbitrarily assigned 
the ddname DD2 in the IEHPROGM examples. DD statements defining 
additional mountable devices are assigned names DD3, DD4, etc. Jd 


C 


C 


Restrictions 


Refer to “Appendix C: DD Statements for Defining Mountable Devices”’ for 
instructions on defining mountable volumes. 


e The block size for the SYSPRINT (message) data set must be a multiple of 
121. The block size for the SYSIN (control) data set must be a multiple of 80. 
Any blocking factor can be specified for these block sizes. 


e With the exception of the SYSIN and SYSPRINT DD statements, all DD 
statements in Table 49 are used as device allocation statements, rather than as 
true data definition statements. Because IEHPROGM modifies the internal 
control blocks created by device allocation DD statements, these statements 
must not include the DSNAME parameter. (All data sets are defined explicitly 
or implicitly by utility control statements.) 


e One anynamel DD statement must be included for each permanently mounted 
volume referred to in the job step. 


e One anyname2 DD statement must be included for each mountable device to 
be used in the job step. 


e When IEHPROGM is dynamically invoked in a job step containing a program 
other than IEHPROGM, the DD statements defining mountable devices for 
IEHPROGM must be included in the job stream prior to DD statements 
defining data sets required by the other program. 


e For VS2 applications, DD statements defining mountable devices must appear 
in the same order in the input stream as the utility control statements that 
refer to volumes mounted on those devices. 


PARM Information on the EXEC Statement 


Additional information can be specified in the PARM parameter of the EXEC 
statement to control the number of lines per page on the output listing and to 
suppress printing of utility control statements. The EXEC statement can be 
coded: 


// EXEC PGM=IEHPROGMI,PARM='‘LINECNT=xx, {PRINT} ] 
{NOPRINT} 


The LINECNT parameter specifies the number of lines per page in the listing of 
the SYSPRINT data set; xx is a 2-digit number, from 01 through 99. If 
LINECNT is omitted, or if an error is encountered in the LINECNT 
subparameter, the number of lines per page will be 45. 


The PRINT value specifies that the utility control statements are to be written to 
the SYSPRINT data set. If neither PRINT nor NOPRINT is coded, PRINT is 
assumed. 


The NOPRINT value specifies that utility control statements are not to be 
written to the SYSPRINT data set. Suppressing printing of utility control 
statements assures that passwords assigned to data sets remain confidential. 
However, suppressing printing may make it difficult to interpret error messages 
because the relevant utility control statement is not printed before the message. 


Utility Control Statements 


IEHPROGM is controlled by the following utility control statements: 


e SCRATCH statement, which is used to scratch a data set or a member from a 
direct access volume. 


e RENAME statement, which is used to change the name or alias of a data set 
or member residing on a direct access volume. 
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SCRATCH Statement 
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¢« CATLG statement, which is used to generate an entry in the index of a 
catalog. 


¢ UNCATLG statement, which is used to remove an entry from the lowest level 
index of the catalog. 


¢ BLDX statement, which is used to create a new index in the catalog. 
¢ DLTX statement, which is used to remove a low level index from the catalog. 


¢« BLDA statement, which is used to assign an alias to an index at the highest 
level of the catalog. 


¢ DLTA statement, which is used to delete an alias previously assigned to an 
index at the highest level of the catalog. 


« CONNECT statement, which is used to place an entry into an index at the 
highest level of the catalog. 


¢ RELEASE statement, which is used to remove an entry from the high level 
index of a volume. 


¢ BLDG statement, which is used to build an index for a generation data group 
and to establish the action to be taken should the index overflow. 


e ADD statement, which is used to add a password entry in the PASSWORD 
data set. 


e REPLACE statement, which is used to replace information in a password 
entry. 


¢ DELETEP statement, which is used to delete an entry in the PASSWORD 
data set. 


e LIST statement, which is used to format and list information from a password 
entry. 


The SCRATCH statement is used to scratch a data set or member from a direct 
access volume. A data set or member is scratched only from the volumes 
designated in the SCRATCH statement. This function does not uncatalog 
scratched data sets. 


The format of the SCRATCH statement is: 


where: 


DSNAME= name 
specifies the fully-qualified name of either the data set to be scratched or the 
partitioned data set that contains the member to be scratched. 


VTOC 
specifies that all data sets on the specified volume, except those protected by a 
password or those whose expiration dates have not expired, are to be 
scratched. Password-protected data sets are scratched if the correct password 
is provided. The effect of VTOC is modified when it is used with PURGE or 
SYS. 


ost 


RENAME Statement 


VOL= device = list 
specifies the volume or volumes that contain the data set or sets to be 
scratched. If WTOC is specified, VOL cannot specify more than one volume. 
Caution should be used when specifying WTOC if VOL specifies the system 
residence volume. 


PURGE 
specifies that each data set specified by DSNAME or VIOC be scratched, 
even if its expiration date has not elapsed. If PURGE is omitted, the specified 
data sets are scratched only if their expiration dates have elapsed. 


MEMBER= name 
specifies a member name or alias of a member to be removed from the 
directory of a partitioned data set. If MEMBER is omitted, the entire data set 
or volume of data sets is scratched. 


SYS 
specifies that data sets that are to be scratched have names that begin with 
“AAAAAAAA.AAAAAAAA.AAAAAAAA.AAAAAAAA.” or 
“SYSnnnnn.T” and “F” or “V” in position 19. These are names assigned to 
data sets by the operating system. This parameter is valid only when VTOC is 
specified. 

If the name of the data set to be scratched begins with SYS, nnnn is the date. 


When executing a SCRATCH operation, care should be taken to ensure that the 
data set or volume is not being used by a program executing concurrently. 


The RENAME statement is used to change the true name or alias of a data set 
or member residing on a direct access volume. The name is changed only on the 
designated volume(s). The rename operation does not update the catalog. 


The format of the RENAME statement is: 


[ label] RENAME DSNAME= name 
VOL= device = lis! 
NEWNAME= name 
[MEMBER= name } 
where: 
DSNAME= name 


specifies the fully qualified name of the data set to be renamed or specifies the 
data set that contains the member to be renamed. 


VOL= device = list 
specifies the volume or volumes that contain the data set or member whose 
name is to be changed. If MEMBER is specified, VOL cannot specify more 
than one volume. 


NEWNAME= name 
specifies the new fully-qualified name for the data set, or the new member or 
alias. 


MEMBER= name 
specifies the name or alias for a member (in the named data set) that is to be 
renamed. If MEMBER is omitted, the specified data set name is changed. 
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CATLG Statement 


UNCATLG Statement 
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The CATLG statement is used to generate an entry in the index of a catalog. If 
additional levels of indexes are required in the catalog, this function automatically 
creates them. When cataloging generation data sets, refer to ‘“‘BLDG (Build 
Generation Data Group Index) Statement”’ for the action to be taken when the 
index is full. 


The format of the CATLG statement is: 


where: 


DSNAME= name 
specifies the fully-qualified name of the data set to be cataloged. The qualified 
name must not exceed 44 characters, including delimiters. 


VOL= device = list 
specifies the volume or volumes that contain the data set to be cataloged. For 
either a sequential data set or an indexed-sequential data set, the volume serial 
numbers must appear in the same order in which they were originally 
encountered (in DD statements within the input stream) when the data set 
was created. All serial numbers specified in VOL must represent the same 
device type. 


CVOL= device = serial 
specifies the device type and volume serial number of the control volume on 
which the catalog search for the index is to begin. If CVOL is omitted, the 
system residence volume is assumed. If the volumes are connected at the 
highest level of the index and the control volume is mounted, CVOL need not 
be specified. 


Note: When device is represented by a group name (for example, SYSDA) 
instead of a generic name (for example, 2314 or 2400) in the VOL parameter, 
the catalog operation does not enter the device type code in the system catalog. 
Instead, it places a unique entry in the device type field of the catalog. The 
allocation of the device for this entry may not be satisfactory to the user. The 
generic name should be used if the group name was generated for one or more 
device types. When the system is subsequently generated, this entry may no 
longer be valid; that is, all such group name entries should be uncataloged and 
then recataloged after a subsequent generation of the system. 


When cataloging data sets residing on tape, specify the data set sequence number 
and the volume serial number, as follows: 


VOL=device=({serial,seqno}.,...) 


If a data set is created on a 9-track dual-density tape unit (2400-4), the data set 
can be cataloged with a device specification of 2400 for an 800 bits per inch 
tape or 2400-3 for a 1600 bits per inch tape. If a device specification of 2400-4 
is made when the data set is cataloged, any subsequent retrieval of that data set 
is made on a dual density unit. 


The UNCATLG statement is used to remove an entry from the lowest level 
index of the catalog. This function does not delete higher level indexes from the 
index structure. 


The format of the UNCATLG statement is: 


where: 


DSNAME= name 
specifies the fully qualified name of the data set to be uncataloged. 


CVOL= device = serial 
specifies the device type and volume serial number of the control volume at 
which the search for the catalog entry is to begin. If CVOL is omitted, the 
system residence volume is assumed. If catalogs are properly connected at the 


highest level of the index and the control volume is mounted, CVOL need not 
be specified. 


BLDX (Build Index) Statement 


The BLDX statement is used to create a new index in the catalog. If the creation 
of an index requires that higher level indexes be created, this function 
automatically creates them. 


The format of the BLDX statement is: 


where: 


INDEX= name 
specifies the qualified name of the index to be created. The qualified name 
must not exceed 44 characters, including delimiters. 

CVOL= device = serial 
specifies the device type and volume serial number of the control volume on 


which the search for the index is to begin. If CVOL is omitted, the system 
residence volume is assumed. 


DLTX (Delete Index) Statement 


The DLTX statement is used to remove an index from the catalog. Only an 
index that has no entries can be removed. 


The format of the DLTX statement is: 


| 
q 


where: 


INDEX= name fa 


specifies the qualified name of the index to be deleted. The qualified name 
must not exceed 44 characters, including delimiters. 


CVOL= device = serial 
specifies the device type and volume serial number of the control volume on 
which the search for the index is to begin. If CVOL is omitted, the system 
residence volume is assumed. 


Because this function does not delete higher level indexes, it must be used 
repetitively to delete an entire structure. For example, to delete index structure 
A.B.C, delete index A.B.C, index A.B, and index A. 
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BLDA (Build Index Alias) Statement 


The BLDA statement is used to assign and alias to an index at the highest level 
of the catalog. 


The format of the BLDA statement is: 
[ abel] BLDA INDEX= name 


[(CVOL= device = serial | 


where: 


INDEX= name 
specifies the unqualified name of the index to which an alias name is to be 
assigned. The unqualified name must not exceed 8 characters. 


ALIAS= name 
specifies an unqualified name to be assigned as the alias. The unqualified name 
must not exceed 8 characters. 


CVOL= device = serial 
specifies the device type and volume serial number of the control volume on 
which the catalog entry is to be made. If CVOL is omitted, the system 
residence volume is assumed. 


DLTA (Delete Index Alias) Statement 


CONNECT Statement 
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The DLTA statement is used to delete an alias previously assigned to an index at 
the highest level of the catalog. 


The format of the DLTA statement is: 


[ abel} DLTA  ALIAS= name 
[CVOL= device = serial ] 


where: 


ALIAS= name 
specifies the unqualified name of the index alias to be deleted. The unqualified 
name must not exceed 8 characters. 


CVOL= device = serial 
specifies the device type and volume serial number of the control volume 
containing the catalog entry to be deleted. If CVOL is omitted, the system 
residence volume is assumed. 


The CONNECT statement is used to place an entry in the high-level index of 
the catalog. The entry identifies a second volume by its device type and volume 
serial number. In addition, it contains an index name identifying the index to be 
searched for (during subsequent index searches) on the second volume. 


Note: This function does not create an index on the second volume. 
The format of the CONNECT statement is: 
| label] CONNECT INDEX= name’ 
: ~° VOL= device = serial 
{CVOL= device = serial | 


where: 


INDEX= name 
specifies the unqualified index name to be entered in the high level index on 
the first volume. The unqualified name must not exceed 8 characters. 


( VOL= device = serial 


specifies the device type and volume serial number of the second volume. This 
information is placed in the high level index on the first volume. 


CVOL= device = serial 
specifies the device type and serial number of the first volume. If CVOL is 
omitted, the system residence volume is assumed to be the first volume. 


The CONNECT statement does not create a SYSCTLG data set on the 
connected volume. Before cataloging the first data set on a connected volume, 
the user must define a SYSCTLG data set on that volume. This can be done 
with the following DD statement: 


//ddname DD DSNAME=SYSCTLG,UNIT=xxxx, DISP=(,KEEP), 
// SPACE=(CYL, 1), WOLUME=SER=xxxxxx 


If a job requires an auxiliary control volume to complete a catalog search, the 
user need not have the auxiliary control volume mounted before the job is begun. 
(The user does not have to remember the volume on which a particular data set 
is cataloged.) The system directs the operator to mount an auxiliary control 
volume if it is needed. 


However, the auxiliary control volume must be connected to the system residence 
volume by means of the CONNECT verb, as modified for Release 17 of OS. If 
an auxiliary control volume was connected before Release 17 of OS, release the 
auxiliary control volume for all high level indexes on the system residence volume 
that point to that volume, and then use the current CONNECT verb to 

( reconnect the auxiliary control volume with the system residence volume. 


RELEASE (Disconnect) Statement 


The RELEASE statement is used to remove an entry from the high level index 
of a volume. This disconnects, in effect, a second volume from the first volume. 
The RELEASE statement does not delete an index from the second volume. 


The format of the RELEASE statement is: 


where: 
INDEX= name 


specifies the unqualified index name to be removed from the high level index 
of the first volume. The unqualified name must not exceed 8 characters. 


CVOL= device = serial 
specifies the device type and volume serial number of the first volume. If 
CVOL is omitted, the system residence volume is assumed to be first volume. 


BLDG (Build Generation-Data-Group Index) Statement 


The BLDG statement is used to build an index for a generation data group, and 
to establish the action to be taken should the index overflow. 
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The format of the BLDG statement is: 
[label] BLDG INDEX= name 


_ ENTRIES= n 
[CVOL= device = serial | 
[EMPTY] 
[DELETE] 
where: 
INDEX= name 
| specifies the 1- to 35-character qualified name of the generation-data-group 
index. 
ENTRIES= n 


specifies the number of entries to be contained in the generation-data-group 
index; m must not exceed 255. 
CVOL= device = serial 
specifies the device type and volume serial number of the volume on which the 
catalog search for the index is to begin. If CVOL is omitted, the system 
residence volume is assumed. 
EMPTY 
specifies that all entries be removed from the generation-data-group index 
when it overflows. This uncatalogs, in effect, all of the generation data sets. If 
EMPTY is omitted, the entries with the largest generation numbers will be 
maintained in the catalog when the generation-data-group index overflows. 
DELETE 
specifies that generation data sets are to be scratched after their entries are 


removed from the index. If DELETE is omitted, the data sets are not 
scratched. 


ADD (Add a Password) Statement 


The ADD statement is used to add a password entry in the PASSWORD data 
set. When the control entry for a direct access, online data sets is added, the 
indicated protection status of the data set is set in the DSCB; when a secondary 
entry is added, the protection status in the DSCB is not changed. 


The format of the ADD statement is: 
[/abei} ADD ~ DSNAME= name 
[PASWORD2= new-password ] 
[CPASWORD= control-password | 
[TYPE= code } | 
_ WVOL= device = list] 
 [DATA=* user-data’] 
where: 


DSNAME= name 


specifies the fully-qualified name of the data set to which the password is to 
be assigned. 


PASWORD2= new-password 
specifies the password to be added. The password can consist of one- to 
eight-alphameric characters. If PASWORD2 is omitted, the operator is 
prompted for a new password. 
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CPASWORD= control-password 


specifies the control password for the data set. The control password must be 
specified unless this is the first password assigned to the data set. 


TYPE= code 
specifies the protection code of the password and, if a control password is 
being assigned to a direct access, online data set, specifies the protection 
status of the data set. If this parameter is omitted, the new password is 
assigned the same protection code as the control password for the data set. If 
a control password is being added, TYPE=3 is the default. The values that 
can be specified for code are: 


1 
specifies that the password is to allow both read and write access to the 


data set; if a control password is being assigned, read/write protection is 
set in the DSCB. 


specifies that the password is to allow only read access to the data set; if a 
control password is being assigned, read/write protection is set in the DSCB. 


specifies that the password is to allow both read and write access to the 
data set; if a control password is being assigned, read-without-password 
protection is set in the DSCB. 


VOL= device = list 
specifies the direct access volume or volumes that contain the data set to be 
protected.If omitted, the protection status of the data set is not set in the 
DSCB, unless the data set is cataloged. This parameter is not necessary for 


secondary password entries or if the desired protection status is already set in 
the DSCB. 


DATA=‘ user-data’ 
specifies that user data is to be included in the password entry. The user data 
must be in single quotes and must not exceed 77 characters. 


REPLACE (Replace a Password) Statement 


The REPLACE statement is used to replace any or all of the following 
information in a password entry: the password name, protection mode (read/write 

or read-only) of the password, and user data. When the control entry for a direct 
access, Online data set is replaced, the protection status of the data set is changed 
in the DSCB if necessary; when a secondary entry is replaced, the protection 
status in the DSCB is not changed. 


The format of the REPLACE statement is: 


DSNAME= name 
specifies the fully qualified name of the data set whose password entry is to be 
changed. 


IEHPROGM Program 335 


PASWORD1= current-password 
specifies the current password in the entry to be changed. If PASWORDI is 
omitted, the operator is prompted for the current password. 


PASWORD2= new-password 
specifies the new password to be assigned to the entry. If the password is not 
to be changed, the current password must also be specified as the new Jo 
password. The password can consist of one- to eight-alphameric characters. If 
PASWORD2Z7 is omitted, the operator is prompted for a new password. 


CPASWORD= control-password 
specifies the control password for the data set whose entry is to be changed. 
The control password must be specified unless the control entry is being 
changed. If the control entry is to be changed, the control password must be 
specified as PASWORD1. 


TYPE= code 
specifies the protection code of the password and, if a control password entry 
is to be changed for a direct access, online data set, specifies the protection 
status of the data set. If this parameter is omitted, the protection is not 
changed. The values that can be specified for code are: 


1 
specifies that the password is to allow both read and write access to the 
data set; if a control password is being changed, read/write protection is set 
in the DSCB. 


specifies that the password is to allow only read access to the data set; if a 
control password is being changed, read/write protection is set in the DSCB. 


specifies that the password is to allow both read and write access to the 
data set; if a control password is being changed, read-without-password 
protection is set in the DSCB. 


VOL= device = list 
specifies the direct access volume or volumes that contain the data set whose 
protection status is to be changed. If omitted, the protection status of the data 
set is not changed in the DSCB, unless the data set is cataloged. This 
parameter is not necessary for secondary password entries or if the protection 
Status of the data set is not to be changed. 


DATA=‘ user-data’ 
specifies that user data is to be included in the password entry. The user data 
must be in single quotes and must not exceed 77 characters. If this parameter 
is omitted, the user data is not changed. 


DELETEP (Delete a Password) Statement 


The DELETEP statement is used to delete an entry in the PASSWORD data set. 
If a control entry is deleted, all the secondary entries for that data set are also 
deleted. If a secondary entry is deleted, only that entry is deleted. When the 
control entry for a direct access, online data set is deleted, the protection status 
in the DSCB is set to indicate that the data set is no longer protected. 


The format of the DELETEP statement is: 
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where: 


DSNAME= name 
specifies the fully qualified name of the data set whose password is to be 
deleted. 


PASWORD1= current-password 
specifies the password to be deleted. 


CPASWORD= control-password 
specifies the control password for the data set whose password is to be 
deleted. The control password must be specified unless the control password is 


to be deleted. If the control password is to be deleted, the control password 
must be specified as PASWORDI. 


VOL= device = list 
specifies the direct access volume or volumes that contain the data set whose 
passwordis to be deleted. If omitted, the protection status of the data set is 
not changed in the DSCB, unless the data set is cataloged. This parameter is 
not necessary if a secondary password is to be deleted. 


LIST (List Information from a Password) Statement 


IEHPROGM Examples 


The LIST statement is used to format and print information from a password 
entry. 


The format of the LIST statement is: 
[ label| LIST DSNAME= name 
PASWORD I= current-password 
where: 


DSNAME= name 
specifies the fully qualified name of the data set whose password entry is to be 
listed. 


PASWORD1= current-password 
specifies the password in the entry to be listed. 


The following examples illustrate some of the uses of IEHPROGM. Table 50 can 
be used as a quick reference guide to IEHPROGM examples. The numbers in the 
‘“Example”’ column point to the examples that follow. 
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Table 50. IEHPROGM Example Directory 


Mountable 

Operation Volumes Comments Example 
SCRATCH 2314 Disk VTOC ts to be scratched. | 
SCRATCH 2314 Disk Two data sets are to be scratched and 
UNCATLG, uncataloged. An index structure is to be deleted 
and DLTX from SYSCTLG. 2. 
RENAME, 2314 Disks A data set is to be renamed on two mountable 
UNCATLG, devices; the old data set name and index 
DLTX, and structure are to be removed from the catalog. The 
CATLG data set is cataloged under its new name. Object 

data set resides on two mountable devices. 3 
UNCATLG 2314 Disk Three data sets are to be uncataloged: their 
and DLTX supporting index structures are to be deleted 

from the catalog. 4 
CONNECT 2314 Disk Connect system residence volume to a second 
and CATLG volume. Catalog data sets on second volume. 

SYSCTLG was previously defined on the second 

volume. 5 
BLDG None A generation-data-group index is to be built. 6 
BLDG and None A generation-data-group index is to be built and 
CATLG three data sets are to be cataloged. 7 
RENAME, 2314 Disk The object data set exists on one mountable 
DELETEP, device. 
and ADD 8 
LIST and 2314 Disk The object data set exists on two mountable 
REPLACE devices. 9 
RENAME 2314 Disk Rename a member of a partitioned data set. 10 


In the IEHPROGM examples, the EXEC statement and the SYSPRINT DD 
statement can be replaced with the following job control statement: 


// EXEC PROC=MOD 
which invokes the following IBM-supplied cataloged procedure: 


//MOD EXEC PGM=IEHPROGM,REGION=44K 
//DDSRV DD VOLUME=REF=SYS1.SVCLIB,DISP=OLD 
//SYSPRINT DDSYSOUT=A 


Note: In the IEHPROGM examples, the DD1 DD statement always refers to the 
system residence volume. 


In the following example, data sets are to be scratched from the volume table of 
contents of a mountable volume. Because the system residence volume is not 
referred to, no DD1 DD statement is necessary in the job stream. 


The example follows: 


Jf /SCRVTOC. JOB 094550, BROWN 


// EXEC PGM=IEGPROGM 

J/SYSPRINT DD SYSOUT=A 

if DD2 DD UNIT=2314, VOLUME=SER=231400,DISP=OLD 
J7SYSIN DD * 


SCRATCH VTOC, VOL=2314=231400 
/* 
The SCRATCH statement, used in this example, indicates that all data sets 
(including those beginning with AAAAAA.AAAAAA.AAAAAA.AAAAAA) 
whose expiration dates have expired are to be scratched from the specified 
volume. 


J 
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In this example, two data sets are to be scratched: SET1 is to be scratched on 
volume 231400, and A.B.C.D.E is to be scratched on volume 231400. Both data 
sets are to be uncataloged, and index structure A.B.C.D is to be deleted from the 
SYSCTLG data set. Because the system residence volume, which resides on a 
3330 volume, is referred to through use of the UNCATLG and DLTX 
statements, a DD statement is included in the input stream. 


The example follows: 


f7/SCRDSETS JOB. 097550, BROWN 


i] EXEC PGM=IEHPROGM 

//SYSPRINT DD  SYSOUT=A 

//DD1 DD UNIT=3330, VOLUME=SER=111111,DISP=OLD 
//DD2 DD UNIT=2314,DISP=OLD, VOLUME=SER=231400 
//SYSIN DD * 


SCRATCH DSNAME=SET 1, VOL=2314=231400 
UNCATLG DSNAME=SET 1 
SCRATCH DSNAME=A.B.C.D.E, VOL=23 14=231400 
UNCATLG DSNAME=A.B.C.D.E 
DLTX INDEX=A.B.C.D 
DLTX INDEX=A.B.C 
DLiTX INDEX=A.B 
DLTX INDEX=A 
/* 


The control statements are discussed below: 


e The first SCRATCH statement specifies that SET1, which resides on volume 
231400, is to be scratched. 


¢ The first UNCATLG statement specifies that SET1 is to be uncataloged. 


« The second SCRATCH statement specifies that A.B.C.D.E, which resides on 
volume 231400, is to be scratched. 


e The second UNCATLG statement specifies that A.B.C.D.E is to be 
uncataloged. 


e The DLTX statements remove one level at a time of the remaining A.B.C.D 
index from the catalog. Index level D is removed, then C, B, and A. 


In this example, the name of a data set is to be changed on two mountable 
volumes. The old data set name and index structure are to be removed from the 
catalog and the data set is to be cataloged under its new data set name. 


The example follows: 


72 

//RENAMEDS JOB 09#550,BROWN 
Ig EXEC PGM=IEHPROGM 
//SYSPRINT DD  SYSOUT=A 
FP Abibn DD  VOLUME=SER=111111,UNIT=3330,DISP=OLD 
/ /DD2 DD  UNIT=(2314,,DEFER),DISP=OLD, 
// SIOLUME=( PRIVATE, SER=( 231400, 231401)) 
//SYSIN DD * 

RENAME DSNAME=A.B.C,NEWNAME=NEWSET, hc 


VOL=2314=( 231400,231401 ) 
UNCATLG DSNAME=A.B.C 
DLTX INDEX=A.B 
DLTX INDEX=A 
CATLG DSNAME=NEWSET, VOL=2314=( 231400,231401 ) 


/* 


IEHPROGM Program 339 


The control statements are discussed below: 


¢ RENAME specifies that data set A.B.C, which resides on volumes 231400 
and 231401, is to be renamed NEWSET. 


e UNCATLG specifies that data set A.B.C is to be uncataloged. 

e The DLTX statements remove remaining index levels B and A. 

¢ CATLG specifies that NEWSET, which resides on volumes 231400 and 
231401, is to be cataloged. 
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In this example, three data sets—A.B.C.D.E.F.SET1, A.B.C.G.H.SET2, and 
A.B.1.J.K.SET3—are to be uncataloged and their supporting index structures 
deleted from the catalog. The system residence volume resides on a 2314 volume. 


The example follows: 


//DLTSTRUC JOB 09#550, BROWN 


lah EXEC PGM=IEHPROGM 

J/SLSPRLNY DD SYSOUT=A 

//DD1 DD UNTT=2314, VOLUME=SER=111111,DISP=OLD 
FP SYSIN DD * 


UNCATLG DSNAME=A.B.C.D.E. 
UNCATLG DSNAME=A.B.C.G.H.SET2 
UNCATLG DSNAME=A.B.1.0.K.SET3 


DLTX INDEX=A.B.T.J.K 
DLTX TINDEX=A.B.1.Jd 
DLTX INDEX=A.B.T1 

DLTX INDEX=A.B.C.G.H 
DLTX INDEX=A.B.C.G 
DLTX TNDEX=A.B.C.D.E.F 
DLTX INDEX=A.B.C.D.E 
DET x INDEX=A.B.C.D 
DLTX INDEX=A.B.C 

DLTX INDEX=A.B 


DLTX INDEX=A 
/* 


The control statements are discussed below: 


e The UNCATLG statements specify that data sets A.B.C.D.E.F.SET1, 
A.B.C.G.H.SET2, and A.B.I.J.K.SET3 are to be uncataloged. 


e« The DLTX statements remove one level at a time of the index structures 
associated with the uncataloged data sets. 
IEHPROGM Example 5 


In this example, the system residence volume, which resides on a 3330 volume, is 
to be connected to a second volume. Any subsequent index search for index level 
X, Y, or Z will be carried to the second volume. 
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IEHPROGM Example 7 


The example follows: 


//CONNECT JOB 09#550, BROWN 
EXEC PGM=IEHPROGM 
//SYSPRINT DD SYSOUT=A 
J 7D): DD UNIT=3330, VOLUME=SER=111111,DISP=OLD 
//DD2 DD UNIT=2314, VOLUME=SER=231400,DISP=OLD 
//SYSIN DD * 
CONNECT INDEX=X , VOL=23 14=231400 
CONNECT INDEX=Y , VOL=23 14=231400 
CONNECT INDEX=Z , VOL=2314=231400 
CATLG DSNAME=X.BB.CCC, VOL=2314=231401 , CVOL=2314=231400 
CATLG DSNAME=Y .BB.CC, VOL=2314=231401 ,CVOL=2314=231400 
CATLG DSNAME=Z. BB. XT, VOL=2314=231401,CVOL=2314=231400 
/* 
The control statements are discussed below: 
e The CONNECT statements identify the second volume. The specified index 


names, along with the volume identification, are placed on the system 
residence volume. 


e The CATLG statements catalog three data sets (X.BB.CCC, Y.BB.CC, and 
Z.BB.XT) on the second volume. Because the volumes are connected before 
the catalog operations are performed, the CVOL parameters are not required 
in the CATLG statements; they are included to bypass the index search on 
the system residence volume. 


In this example, a generation-data-group index is to be built in the catalog. The 
system residence volume resides on a 3330 volume. 


The example follows: 


//BLDGDGIX JOB 09#550,BROWN 


J / EXEC PGM=IEHPROGM 
//SYSPRINT DD SYSOUT=A 
J 7 DD DD UNIT=3330,VOLUME=SER=111111,DISP=OLD 


JF SLSIN DD * 
BLDG INDEX=A.B.C,ENTRIES=10,EMPTY 
/* 


The BLDG statement specifies the generation data group A.B.C and makes 
provision for ten entries in the index. All entries are to be removed from the 
index when it overflows. 


In this example, a generation-data-group index is to be built and three data sets 
¢ 

are to be cataloged in the index. The system residence volume resides on a 3330 

volume. 


The example follows: 


/ /CTLGDG JOB 09#550,BROWN 


ve EXEC PGM=IEHPROGM 
//SYSPRINT DD SYSOUT=A 
7/DD | DD UNIT=3330,VOLUME=SER=111111,DISP=OLD 


//SYSIN DD * : 
BLDG INDEX=A.B.C, ENTRIES=20,EMPTY 
CATLG DSNAME=A.B.C.G0001V00, VOL=2314=231400 
CATLG DSNAME=A.B.C.GOQ002V00, VOL=2314=231400 
CATLG DSNAME=A.B.C.GOO03V00, VOL=2314=231400 
/* 
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The control statements are discussed below: 


¢ BLDG specifies the generation data group A.B.C and makes provision for 20 
entries in the index. All entries are to be removed from the index when it 
overflows. 


« The CATLG statements cataloged three generation data sets. The data sets 
are cataloged with absolute generation numbers 1 through 3. 


Figure 65 shows the index structure after the three generation data sets are 
cataloged. 


A 
B 


C  G0003V00 G0002 V00 GO001V00 
(latest (latest -1) (latest -2) 
generation) 


Figure 65. Index Structure After Generation Data Sets Are Cataloged 


In this example, a data set is to be renamed. The data set passwords assigned to 
the old data set name are to be deleted. Then two passwords are to be assigned 
to the new data set name. 


Note: If the data set is not cataloged, a message indicating that the LOCATE 
macro instruction failed is issued. The return code is 8. 


The example follows: 


Pe 
//ADDPASS JOB 09#550,BROWN 
EXEC PGM=IEHPROGM, PARM='NOPRINT' 
//SYSPRINT DD SYSOUT=A 


Vig ae) Ba DD VOLUME=( PRIVATE, SER=231400 ),DISP=OLD, 
j-7 UNLPAC 231-4; DEFER) 
Lf SL SIN DD = 


RENAME DSNAME=OLD, VOL=2314=231400, NEWNAME=NEW 
DELETEP DSNAME=OLD, PASWORD1=KEY 
ADD DSNAME=NEW, PASWORD2=KEY, TYPE=1, \ Ve 
DATA='SECONDARY IS READ! 
ADD DSNAME=NEW, PASWORD2=READ ,CPASWORD=KEY,TYPE=2, 4 
DATA='ASSIGNED TO J. DOE' 
/* 


The control statements are discussed below: 


¢ DELETEP specifies that the entry for the password KEY is to be deleted. 
Because KEY is a control password in this example, all the password entries 
for the data set name are deleted. The VOL parameter is not needed because 
the protection status of the data set as set in the DSCB is not to be changed; 
read/write protection is presently set in the DSCB, and read/write protection 
is desired when the passwords are reassigned under the new data set name. 


e The ADD statements specify that entries are to be added for passwords KEY 
and READ. KEY becomes the control password and allows both read and 
write access to the data set. READ becomes a secondary password and allows 
only read access to the data set. The VOL parameter is not needed, because 
the protection status of the data set is still set in the DSCB. 


Note: The operator is required to supply a password to rename the old data set. 
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In this example, information from a password entry is to be listed. Then the 
protection mode of the password, the protection status of the data set, and the 


( user data are to be changed. 
The example follows: 


72 
//REPLPASS JOB 09#550,BROWN 
EXEC PGM=IEHPROGM, PARM='NOPRINT' 
//SYSPRINT DD SYSOUT=A 
//DD1 DD UNIT=3330,VOLUME=SER=111111,DISP=OLD 
//DD2 DD  VOLUME=( PRIVATE, SER=( 231400,231401)), 
// UNIT=(2314,,DEFER ),DISP=OLD 
//SYSIN DD * 
LIST DSNAME=A.B.C, PASWORD1=ABLE 
REPLACE DSNAME=A.B.C,PASWORD1=ABLE, (Cc 
PASWORD2=ABLE,TYPE=3, a te 
VOL=2314=( 231400,231401), \\c 


DATA='NO SECONDARIES; ASSIGNED TO DEPT 31' 
/* 


The control statements are discussed below: 


« LIST specifies that the access counter, protection mode, and user data from 
the entry for password ABLE are to be listed. Listing the entry permits the 
content of the access counter to be recorded before the counter is reset to 
zero by the REPLACE statement. 


« REPLACE specifies that the protection mode of password ABLE is to be 
changed to allow both read and write access and that the protection status of 
the data set is to be changed to write-only protection. The VOL parameter is 
required because the protection status of the data set is being changed and the 
data set, in this example, is not cataloged. Because this is a control password, 

C the CPASWORD parameter is not required. 
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In this example, a member of a partitioned data set is to be renamed. 


The example follows: 


/ /REN JOB 09#550,BROWN 
Vie EXEC PGM=IEHPROGM 
{7 DD1 DD VOL=SER=231411,DISP=OLD, UNIT=2314 
//SYSIN DD * 
RENAME VOL=2314=231411,DSNAME=DATASET ,NEWNAME=BC , MEMBER=ABC 
/* 


The control statements are discussed below: 


e DD1 DD defines a permanently mounted volume. ne 


e SYSIN DD defines the input data set, which immediately follows in the input 
stream. 


« RENAME specifies that member ABC in the partitioned data set DATASET, 
which resides on a 2314 volume, is to be renamed BC. 
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IFHSTATR Program 


IFHSTATR is a system utility used to format and print information from type 21 
(error statistics by volume) records. (See “Introduction’’ for general system utility 
information. ) 


Figure 66 shows the format of the type 21 record. 


X‘15' 


Volume Serial Number 
Channel/Unit Address 


UCB Type 
Temporary Read Temporary Write Start |/O's 
Errors Errors 
Permanent Read Permanent Write Noise Blocks Erase Gaps 
Errors Errors 
Erase Gaps Cleaner Actions Tape Density 
(continued) 


Figure 66. Type 21 (ESV) Record Format 


Error statistics by volume (ESV) records should be retrieved from the 
IFASMFDP tape or from SYS1.MAN (on tape). ESV can also be retrieved 
directly from SYS1.MANX or SYS1.MANY (on a direct access storage device); 
however, IFHSTATR does not clear the SYSI.MANX (or SYSI.MANY) data 
set or make it available for additional records. 


Input and Output 


IFHSTATR uses as input type 21 records, which contain information about 
errors on magnetic tape. IFHSTATR processes only type 21 records; if none are 
found, a message is written to the output data set. 


IFHSTATR produces as output an output data set, which contains information 
selected from type 21 records. The output takes the form of 121-byte unblocked 
records, with an ASA control character in the first byte of each record. 


Figure 67 shows a sample of printed output from IFHSTATR. 


VOLUME CPU TIME CHANNEL TEMP TEMP PERM PERM NOISE ERASE CLEANER USAGE TAPE BLOCK 


SERIAL DATE ID OF DAY / UNIT READ WRITE READ WRITE BLOCKS GAPS ACTIONS (SIO's) DENSITY LENGTH 


001021 69/309 BB 15:55:07 181 ] 0800 80 
001022 69/309 AA 15:56:02 184 10 1600 121 
000595 69/309 cc 15:56:20 283 0800 50 


Figure 67. Sample Output from IFHSTATR 
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Control 


IFHSTATR is controlled by job control statements. Utility control statements are 
not used. 


Job Control Statements 


Table 51 shows the job control statements necessary for using IFHSTATR. 
Table 51. IFHSTATR Job Control Statements 


Statement Use 
JOB Initiates the job. 
EXEC Specifies the program name (PGM=IFHSTATR). 


SYSUT!1 DD _ Defines the input data set and the device on which it resides. The DSNAME, 
UNIT, VOLUME, LABEL, DCB, and DISP parameters should be included. 


SYSUT2 DD _ Defines the sequential data set on which the output is to be written. 


The output data set can reside on any output device supported by BSAM. 


Note: The LRECL and BLKSIZE parameters are not specified by IFHSTATR. 
This information is taken from the DCB parameter on the SYSUT1 DD 
statement or from the tape label. 


IFHSTATR Example 
This example shows the JCL needed to produce a report. 
The example follows: 


17: JOB 

fy EXEC PGM=IFHSTATR 

Ji SYST 1 DD UNIT=2400,DSNAME=SYS1.MAN,LABEL=(,SL), 
// VOLUME=SER=VOLID, DISP=OLD 
J {Scout DD SYSOUT=A > 
/* 
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Appendix A: Exit Routine Linkage 


Utility programs can be linked to user-supplied exit routines for additional 
processing. 


Linking to an Exit Routine 


Linking to an exit routine from a utility program is accomplished in one of the 
following ways: 


e If the exit routine is for label processing or totaling, or if the exit routine is 
specified in the IEBTCRIN program by OQUTREC or ERROR, linkage is 
performed by the BALR instruction. 


e In all other cases, linkage is performed by using the LINK macro instruction. 


The LINK macro instruction contains the symbolic name of the entry point of an 
exit routine and, if required, a list of parameters. 


For further information on the use of the LINK macro instruction, see OS/VS 
Supervisor Services and Macros, GC27-6979, and OS/VS Data Management 
Macro Instructions , GC26-3793. 


At the time of the linkage operation: 


e General register 1 contains the starting address of the parameter list, or 
contains zero to indicate end-of-file on the input data set for the IEBTCRIN 
OUTREC or ERROR exits. 


e General register 13 contains the address of the register save area. This save 
area must not be used by user label processing routines. See ‘“‘Appendix E: 
Processing User Labels.” 


¢ General register 14 contains the address of the return point in the utility 
program. 


e General register 15 contains the address of the entry point to the exit routine. 


Registers 1 through 14 must be restored before control is returned to the utility 
program. 


The exit routine must be contained in either the job library or the link library. 


The parameter lists passed to label processing routines and parameter lists passed 
to non-label-processing routines are described in the topics that follow. 


Label-Processing Routine Parameters 


The parameters passed to a user’s label-processing routine are addresses of the 
80-byte label buffer, the DCB being processed, the status information if an 
uncorrectable input/output error occurs, and the totaling area. 


The 80-byte label buffer contains an image of the user label when an input label 
is being processed. When an output label is being processed, the buffer contains 
no significant information at entry to the user’s label-processing routine. When 
the utility program has been requested to generate labels, the label-processing 
routine constructs a label in the label buffer. 
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If standard user labels (SUL) are specified on the DD statement for a data set, 
but the data set has no user labels, the system still takes the specified exits to the 
appropriate user’s routine. In such a case, the user’s input label-processing 
routine is entered with the buffer address parameter set to zero. 


The format and content of the DCB are presented in OS/VS Data 
Management Macro Instructions, GC26-3793. 


Bit O of flag 1 in the DCB-address parameter is set to a value of 0 except when: 
¢ Volume trailer or header labels are being processed at volume switch time. 


¢ The trailer labels of a MOD data set are being processed (when the data set is 
opened). 


If an uncorrectable input/output error occurs while reading or writing a user 
label, the appropriate label-processing routine is entered with bit O of flag 2 in 
the status-information-address parameter set on. The three low-order bytes of 
this parameter contain the address of standard status information as supplied for 
SYNAD routines. (The SYNAD routine is not entered.) 


Non-Label-Processing Routine Parameters 


Table 52 shows the program from which exits can be taken to 
non-label-processing routines, the names of the exits, and the parameters 
available for each exit routine. 


Table 52. Parameter Lists for Non-Label Processing Exit Routines 


Program Exit Parameters 
IEBGENER KEY Address at which key is to be placed (record follows key): 
address of DCB. 
DATA Address of SYSUT1 record: address of DCB. 


IOERROR Address of DECB; cause of the error and address of DCB. 
(Address in lower order three bytes and cause of error in high 
order byte.) 


IEBCOMPR ~~ ERROR Address of DCB for SYSUTI: address of DCB for SYSUT2.' 
PRECOMP Address of SYSUTI record: length of SYSUTI record, address 
of SYSUT2 record; length of SYSUT2 record. 


IEBPTPCH INREC Address of input record; length of the input record. 
OUTREC Address of output record: length of output record. 
IEBTCRIN ERROR Address of the error record; address of a full word which 
contains the record length. 
OUTREC Address of the normal record; address of a full word which 


contains the record length. 


' The IOBAD pointer in the DCB points to a location that contains the address of the 
corresponding data event control block (DECB) for these records. The format of the DECB 
is illustrated as part of the BSAM READ macro instruction in OS/VS Data Management 
Macro Instructions, GC26-3793. 


Returning from an Exit Routine 


An exit routine returns control to the utility program by means of the macro 
return instruction in the exit routine. 


The format of the RETURN macro instruction is: 
[Jabel] RETURN’ = {(rJ,r2)] 
:  RC=fn} 
{15 
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where: 


(r/sr2) 
specifies the range of registers to be reloaded by the utility program from the 
register save area. If this parameter is omitted, the registers are considered 
properly restored by the exit routine. 


RC= 
specifies a return code in register 15. If RC is omitted, register 15 is loaded as 
specified by (r /,r2). These values can be coded: 


n 
specifies a return code to be placed in the 12 low order bits of register 15. 


15 
specifies that general register 15 already contains a valid return code. 


The user’s label-processing routine must return a code in register 15 as shown in 
Table 53 unless: 


¢« The buffer address was set to zero before entry to the label processing 
routine. In this case, the system resumes normal processing regardless of the 
return code. 


e The user’s label-processing routine was entered after an uncorrectable output 
error occurred. In this case the system attempts to resume normal processing. 


Table 53 shows the return codes that can be issued to utility programs by user 
exit routines. Slightly different return codes are used for the 
UPDATE=INPLACE option of the IEBUPDTE program. See the discussion of 
UPDATE=INPLACE in the chapter “IEBUPDTE Program.” 
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Table 53. Return Codes Issued by User Exit Routines 


Type of Exit 


Input Header or 
Trailer Label 


Output Header or 
Trailer Label 


Totaling Exits 


All other exits 
(except IEBTCRIN’s 


ERROR and OUTREC) 


ERROR 


OUTREC 


Return 
Code 


0 


16 


0-11 
(Set to 
next 
multiple 
of four) 


12 or 16 


16 


Action 


The system resumes normal processing. If there are 
more labels in the label group, they are ignored. 


The next user label is read tnto the label buffer area and 
control is returned to the user’s routine. If there are no 
more labels, normal processing is resumed. 


The utility program is terminated on request of the user 
routine. 

The system resumes normal processing. 

No label is written from the label buffer area. 


The user label is written from the label buffer area. The 
system then resumes normal processing. 


The user label is written from the label buffer area. If 
fewer than eight labels have been created, the user's 
routine again receives control so that it can create another 
user label. If eight labels have been created, the system 
resumes normal processing. 


The utility program is terminated on request of the user 
routine. 


Processing continues, but no further exits are taken. 
Normal operation continues. 


Processing ceases, except for EOD processing on output 
data set (user label processing). 


Utility program is terminated. 


Return code is compared to highest previous return code; 
the higher is saved and the other discarded. At the normal 
end of job, the highest return code is passed to the 

calling processor. 


Utility program is terminated and this return code is 
passed to the calling processor. 


Record is not placed in the error data set. Processing 
continues with the next record. 


Record is placed in the error data set (SYSUT3). 


Record is not placed in error data set but is processed as a 
valid record (sent to OUTREC and SYSUT2 if specified). 
IEBTCRIN removes the EDW from an edited MTDI 
record before processing continues. 


Utility program is terminated. 
Record is not placed in normal output data set. 
Record is placed in normal output data set (SYSUT2). 


Utility program is terminated. 


Further information on the use of the RETURN macro instruction is contained in 
OS/VS Supervisor Services and Macros, GC27-6979. 
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Appendix B: Invoking Utility Programs from a Problem Program 


Utility programs can be invoked by a problem program through the use of the 
ATTACH or LINK macro instruction. In addition, IEBTCRIN can be invoked 
through the use of the LOAD or CALL macro instruction. 


The problem program must supply the following to the utility program: 


e The information usually specified in the PARM parameter of the EXEC 
statement. 


e The ddnames of the data sets to be used during processing by the utility 
program. 


Note: When IEHMOVE, IEHPROGM, or IEHLIST is dynamically invoked in a 
job step containing a program other than one of these three, the DD statements 
defining mountable devices for the IEHMOVE, IEHPROGM, or IEHLIST 
program must be included in the job stream prior to DD statements defining data 
sets required by the other program. 


LINK or ATTACH Macro Instruction 


The LINK or ATTACH macro instruction can be used to invoke a utility 
program from a problem program. 


The format of the LINK or ATTACH macro instruction is: 


where: 


EP= progname 
specifies the symbolic name of the utility program. 


PARAM= 
specifies, as a sublist, address parameters to be passed from the problem 
program to the utility program. These values can be coded: 


optionaddr 
specifies the address of an option‘list, which is usually specified in the 
PARM parameter of the EXEC statement. This address must be written for 
all utility programs. 


ddnameaddr 
specifies the address of a list of alternate ddnames for the data sets used 
during utility program processing. If standard ddnames are used and this is 
not the last parameter in the list, it should point to a halfword of zeros. If it 
is the last parameter, it may be omitted. 


hdingaddr 
specifies the address of a six-byte list, HDNGLIST, which contains an 
EBCDIC page count for the output device. If hdingaddr is omitted, the 
page number defaults to 1. 


VL=1 
specifies that the sign bit of the last fullword of the address parameter list is 
to be set to 1. 
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Figure 68 shows these lists as they exist in the user’s DC area. Note that the 
symbolic starting addresses for OPTLIST and DDNMELST fall on halfword 
boundaries. Note also the alternative ddnames INSTREAM, INPUTSET, and 
WHICHPTR. 


Full word Full word 
boundary boundary 


Half word Half word 
boundary boundary 


joofos| w fool v fe} ali fel y 

0949600 | 00|00|00|00|00 
yf 

gjoo|ooloofoo| | [| | 


L- 
Starting address of .g0% 
the optionaddr 
parameter list 
(OPTLIST) 


Starting address of 
the ddnameaddr 4» 
parameter list ; 
(DDNMELST) 


Starting address of 
the hdingaddr 

parameter list —— 
(HDNGLIST) a 


Figure 68. Typical Parameter Lists 


The PARAM parameter of the LINK macro instruction in the calling program 
provides the utility program with the symbolic addresses of the parameter lists 
shown in Figure 68, as follows: 


e The option list, OPTLIST, which includes the number of bytes in the list 
(hexadecimal 08) and the NOVERIFY option. 


e The alternate ddname list, DDNMELST, which includes the number of bytes 
in the list (hexadecimal 48) and alternative names for the SYSIN, SYSUT1, 
and SYSUT2 data sets. 


e The heading list, HDNGLIST, which includes the number of bytes in the list 
(hexadecimal 04) and indicates the starting page number (shown as 10) for 
printing operations controlled through the SYSPRINT data set. 


The option list, OPTLIST, must begin on a halfword boundary that is not also a 
fullword boundary. The two high order bytes contain a count of the number of 
bytes in the remainder of the list. (For all programs except IEHMOVE, 
IEHLIST, IEHPROGM, IEHINITT, IEHLIST, and IEBISAM, the count must be 
zero.) OPTLIST is free form with fields separated by commas. No blanks or 
zeros should appear in the list. 


The ddname list, DDNMELST, must begin on a halfword boundary that is not 
also a fullword boundary. The two high order bytes contain a count of the 
number of bytes in the remainder of the list. Each name of fewer than eight 
bytes must be left aligned and padded with blanks. If an alternate ddname is 
omitted from the list, the standard name is assumed. If the name is omitted 
within the list, the eight-byte entry must contain binary zeros. Names can be 
omitted from the end by merely shortening the list. Table 54 shows the sequence 
of the eight-byte entries in the ddname list pointed to by ddnameadar . 


Table 54. Sequence of DDNMELST Entries 


Entry Standard Name 


00000000 
OQO000000 
00000000 
00000000 
SYSIN 
SYSPRINT 
00000000 
SYSUTI 
SYSUT2 
0 SYSUT3 
I SYSUT4 


— —-$- O H~+ Dn BWYN — 


The first two bytes of HDNGLIST contain the length in bytes of the heading list. 
The remaining four bytes contain a page number that the utility program is to 
place on the first page of printed output. 

LOAD Macro Instruction 
IEBTCRIN can be invoked through use of the LOAD macro instruction. 


The LOAD macro instruction causes the control program to bring the load 
module containing the specified entry point into main storage unless a copy is 
already there. Control is not passed to the load module. 


The format of the LOAD macro instruction is: 


EP=JEBTCRIN 
is the entry point name of the program to be brought into main storage. 


EPLOC= address of name 
is the main storage address of the entry point name described above. 


CALL Macro Instruction 


The CALL macro instruction can be used to pass control to IEBTCRIN after 
IEBTCRIN has been loaded into main storage. 


Control can be passed to IEBTCRIN via a CALL macro instruction or via a 
branch-and-link instruction. If the branch-and-link instruction is used, register 1 
must be loaded with the address of a parameter list of full words as described 

| under “LINK or ATTACH Macro Instruction.” The last parameter list address 
must contain X‘80’ in byte 1 to indicate the last parameter in the list. 


The format of the CALL macro instruction is: 


[name] CALL TEBTCRIN(, optionaddr [,ddnameaddr\, ‘DVL 
where: 
IEBTCRIN 


is the name of the entry point to be given control; the name is used in the 
macro instruction as the operand of a V-type address constant. 


optionaddr 
specifies the address of an option list, OPTLIST, usually specified in the 
PARM parameter of the EXEC statement. This address must be written for all 
utility programs. 


Appendix B: Invoking Utility Programs from a Problem Program 353 


354 OS/VS Utilities 


ddnameaddr 
specifies the address of a list of alternate ddnames, DDNMELST, for the data 
sets used during utility program processing. If standard ddnames are used and 
this is not the last parameter in the list it should point to a halfword of zeros. 
If it is the last parameter, it may be omitted. 


hdingaddr 
specifies the address of a six-byte list containing an EBCDIC page count for 
the output device. 


VL 
specifies that the high order bit of the last address parameter in the macro 
expansion is to be set to 1. 


The option list, OPTLIST, must begin on a halfword boundary that is not also a 
fullword boundary. The two high order bytes contain a count of the number of 
bytes in the remainder of the list. (For all programs except IEHMOVE, 
IEHPROGM, IEHINITT, and IEBISAM, the count must be zero.) The option 
list is free form with fields separated by commas. No blanks or zeros should 
appear in the list. 


The ddname list, DDNMELST, must begin on a halfword boundary that is not 
also a fullword boundary. The two high order bytes contain a count of the 
number of bytes in the remainder of the list. Each name of fewer than eight 
bytes must be left-aligned and padded with blanks. If an alternate ddname is 
omitted from the list, the standard name is assumed. If the name is omitted 
within the list, the eight-byte entry must contain binary zeros. Names can be 
omitted from the end by merely shortening the list. The sequence of the 
eight-byte entries in the ddname list pointed to by ddnameaddr is shown earlier 
in Table 54. 


The first two bytes of the heading list, HDNGLIST, contain the length in bytes 
of the heading list. The remaining four bytes contain a page number that the 
utility program is to place on the first page of printed output. 
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Appendix C: DD Statements for Defining Mountable Devices 


When defining mountable devices to be used by system utility programs 
IEHPROGM, IEHMOVE, IEHLIST, or IEHDASDR, the user must consider the 
implications of the DD statements he uses to define those devices. 


DD statement parameters must ensure that no one else has access to either the 
volume or the data set. In any case, caution should be used when altering 
volumes that are permanently resident or reserved (for example, volumes 
containing system data sets, non-dismountable volumes, and volumes reserved 
through the PRESRES option). 


Under normal conditions, a mountable device should not be shared with another 
job step; that is, if a utility program is used to update a volume on a mountable 
device, the volume being updated must remain mounted until the operation is 
completed. 


Following are ways to ensure that mountable devices are not shared: 
e Specify DEFER in a DD statement defining a mountable device. 
e Specify unit affinity on a second DD statement defining a mountable device. 


e Specify a volume count in the VOLUME parameter of a DD statement that is 
greater than the number of mountable devices to be allocated. 


e Specify PRIVATE in a DD statement defining a mountable device. 


For a detailed discussion, see OS/VS JCL Reference , Order Number 
GC28-0618. 


DD Statement Examples 


DD Example 1 


DD Example 2 


In the following examples of DD statements, an IBM 2314 Disk Storage Drive is 
indicated as the mountable device. Alternative parameters are stacked. 


This DD statement makes a specific request for a private, non-sharable volume 
or volumes to be mounted on a single 2314 device. 


The example follows: 


//DD1 DD UNIT=(2314,,DEFER),DISP=(,KEEP), 
VOLUME=( PRIVATE, SER=( 123456 ) ) 


A utility program causes a mount message to be issued for a specific volume 
when the volume is required for processing by the program. The user should 
supply the operator with the clearly marked volume or volumes to be mounted 
during the job step. 


This DD statement ensures that the volume integrity of a mountable volume is 
maintained. If only one volume is to be processed, it is mounted _at the start of 
the job step and dismounted at the end of the step. If additional volumes are 
processed, they are mounted and dismounted when needed by the utility 
program. The last volume to be processed is dismounted at the end of the job 
step. 


This DD statement makes a request for a private, non-sharable volume. 
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DD Example 3 


DD Example 4 


DD Example 5 
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The example follows: 
//DD2 DD UNIT=( 2314, ,DEFER),VOLUME=PRIVATE, DISP=( NEW, KEEP ) 
The results of this statement are identical to those shown in DD Example 1. 


If a specific unit is requested and the volume serial number is not given in the 
DD statement, the user must be certain that either: (1) the desired volume is 
already mounted on that unit, or (2) a volume is not mounted, causing the 
system to issue a mount message. 


Note: This statement can be used only if the user is certain that a removable 
volume, rather than a fixed volume, will be allocated by the scheduler. If there is 
any chance that a fixed volume will be allocated, this statement must not be 
used. 


This DD statement makes a specific request for a private, sharable volume to be 
mounted on a 2314 device. 


The example follows: 
//DD1 DD UNIT=2314 , VOLUME=( PRIVATE, SER=( 121212.) ),DISP=OLD 


This DD statement does not ensure that volume integrity is maintained. It should 
be used with extreme caution in a multiprogramming environment because there 
is the possibility that a job step running concurrently might make a specific 
request for the volume, use the volume, and demount it. 


This DD statement makes a specific request for a public, non-sharable volume to 
be mounted on a 2314 device. 


The example follows: 
//DD3 DS-UNIT=(23 14,7, DEFER), VOLUME=SER=7690 12,D1SP=( ,OLD) 


If the volume is already mounted, it is used. The volume remains mounted at the 
end of the job step, and is not demounted until another job step requires the 
device on which the volume is mounted. 


This DD statement ensures that volume integrity is maintained between jobs; two 
or more such statements in a single job can allocate the same device. 


This DD statement makes a specific request for a public, sharable volume to be 
mounted on a 2314 device. 


The example follows: 
//DD1 DD UNIT=2314,VOLUME=SER=654321,DISP=OLD 


If the volume is already mounted, it is used. The volume remains mounted at the 
end of the job step, and is not demounted until another job step requires the 
device on which the volume is mounted. (This DD statement can also be used to 
define permanently resident devices.) 


This DD statement does not ensure that the volume integrity of a mountable 
volume is maintained. It should be used with extreme caution in a 
multiprogramming environment because there is the possibility that a job step 
running concurrently might use the device. 
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Appendix D: Generation Data Groups 


A generation data group is a group of related cataloged data sets. The manner in 
which these data sets are cataloged is what makes them a generation data group. 
Within a generation data group, the generations can have like or unlike DCB 
attributes and data set organizations. If the attributes and organizations of all 
generations in a group are identical, the generations can be retrieved together as 
a single data set. Each data set within a generation data group is called a 
generation data set. Generation data sets are sometimes called generations. 


There are advantages to grouping related data sets. Because the catalog 
management routines can refer to the information in a special index—called a 
generation index—in the catalog: 


e All of the data sets in the group can be referred to by a common name. 
e The operating system is able to keep the generations in chronological order. 


e QOutdated or obsolete generations can be automatically deleted by the 
operating system. 


The management of a generation data group depends upon the fact that 
generation data sets have sequentially ordered names—absolute and relative 
names—that represent their age. The absolute generation name is the 
representation used by the catalog management routines in the catalog. Older 
data sets have smaller absolute numbers. The relative name is a signed integer 
used to refer to the latest (0), next to the latest (-1), etc. generation. The 
relative number can also be used to catalog a new generation (+1). 


Absolute Generation and Version Numbers 


An absolute generation and version number is used to identify a specific 
generation of a generation data group. The generation and version numbers are 
in the form GxxxxVyy, where xxxx is an unsigned four-digit decimal generation 
number and yy is an unsigned two-digit decimal version number. For example: 


e A.B.C.GOOO0VOO is generation data set zero, version zero in the generation 
data group A.B.C. 


¢ A.B.C.G0001V00 is generation data set one, version zero in generation data 
group A.B.C. 


e A.B.C.GOO09VO1 is generation data set nine, version one in generation data 
group A.B.C. 


The number of new generations and versions is limited by the number of digits in 
the absolute generation name, that is, 9999 for generations and 99 for versions. 


The generation number is automatically maintained by the system. The number 
of generations kept depends on the size of the generation index. For example, if 
the size of the generation index allows ten entries, the ten latest generations may 
be maintained in the generation data group. 


The version number allows you to perform normal data set operations without 
disrupting the management of the generation data group. For example, if you 
want to update the second generation in a three-generation group, replace 
generation two, version zero, with generation two, version one. Only one version 
is kept per generation. 
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A generation can be cataloged using either absolute or relative numbers. When a 
generation is cataloged, a generation and version number is placed as a low level 
entry in the generation data group. In order to catalog a version number other 
than VOO, you must use an absolute generation and version number. 


Figure 69 shows how the generation index looks when three generations are 
cataloged. Note that the generation index is a push-down list, which allows you 
to use relative generation numbers when cataloging or retrieving a generation. 


VTOC 


To 
SYSCTLG 
data set 
ein AN 


Figure 69. Generation Index—Three Entries 


Note: A new version of a specific generation can be cataloged automatically by 
specifying the old generation number along with a new version number. For 
example, if generation A.B.C.GO005V0O0 is cataloged in the generation index, 
and you now create and catalog A.B.C.GOOO5V0O1, the new entry is cataloged in 
the generation index location previously occupied by A.B.C.GO005VO00. This 
process removes the old entry from the catalog but does not scratch the old 
version. To scratch the old version and make its space available for reallocation, 
a DD card, describing the data set to be deleted, with DISP=(OLD,DELETE) 
should be included at the time the data set is to be replaced by the new version. 


Relative Generation Number 
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As an alternative to using absolute generation and version numbers when 
cataloging or referring to a generation, you can use a relative generation number. 
To specify a relative number, use the generation data group name followed by a 
negative integer, a positive integer, or a zero, enclosed in parentheses. For 
example, A.B.C(-1), A.B.C(4+1), or A.B.C(O). 


The value of the specified integer tells the operating system what generation 
number to assign to a new generation, or it tells the system the location (in the 
generation index) of an entry representing a previously cataloged generation. 


When you use a relative generation number to catalog a generation, the operating 
system assigns an absolute generation number and a version number of VOO to 
represent that generation. The absolute generation number assigned depends on 
the number last assigned and the value of the relative generation number that 
you are now specifying. For example, if in a previous job, generation 
A.B.C.G0O005V00 was the last generation cataloged, and you specify A.B.C(4+1), 
the generation now cataloged is assigned the number GOOO6VO00. Though any 
positive relative generation number can be used, a number greater than | may 
cause absolute generation numbers to be skipped. 


When you use a relative generation number to refer to a generation that was 
cataloged in a previous job, the relative number has the following meaning: 


¢ A.B.C(O) refers to the latest existing cataloged entry. 
e A.B.C(-1) refers to the next-to-the-latest entry, etc. 


When cataloging is requested via JCL, all actual cataloging occurs at job 
termination—not at step termination. Because this is so: 


e A relative number used in the JCL refers to the same generation throughout a 
job. 


e A job step that terminates abnormally may be deferred for a later step restart. 
If the step cataloged a generation data set via JCL, you must change all 
relative generation numbers in the succeeding steps via JCL before 
resubmitting the job. 


For example, if the succeeding steps contained the relative generation numbers: 
e A.B.C(+1), which refers to the entry cataloged in the terminated job step. 

e A.B.C(0), which refers to the next to the latest entry. 

« A.B.C(-1), which refers to the latest entry, prior to A.B.C(OQ). 


You must change them as follows before the step can be restarted: A.B.C(O), 
A.B.C(-1), A.B.C(-2), etc. 


Note: New generation data group requests are cataloged with a volume serial 
number of X‘FF4040404040’ if they are not opened, so that data set integrity is 
maintained and an incorrect generation is not retrieved. 


Figure 70 shows how a generation index looks after the same job has been run 
three times and three generations—A.B.C(+1), A.B.C(+1), and 

A.B.C(+1)—have been cataloged via JCL. The first generation is assigned the 
generation number GOOO01VOO; the second, GOOO2V00; the third, GO003VOO. 


(A.B.C. (A.B.C. (A.B.C. 

GOO003V00) GO002V00) G0001V00) 

Last Second First 

cataloged— cataloged— cataloged— 

newest next-to- oldest 

generation latest generation 
generation 


Figure 70. Relative: Positioning—Three Entries in the Catalog 
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Building a Generation Index 


A generation data group is managed via the information found in a generation 
index. The BLDG function builds the index. The BLDG function also indicates 
how older or obsolete generations are to be handled when the index is full. For 
example, when the index is full, you may wish to empty it, scratch existing 
generations, and begin cataloging a new series of generations. 


Note: An alias cannot be assigned to the highest level of a generation index. 


After the index is built, a generation can be cataloged by its generation data 
group name and either an absolute generation and version number or a relative 
generation number. 


Examples showing how to build a generation-data-group index are included in 
“Cataloging a Generation” in this appendix. 


Creating a New Generation 


Allocating a Generation 
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To create a new generation data set: 
e Allocate the generation. 


¢ Catalog the generation. 


To take full advantage of the facilities of the system, the allocation can be 
patterned after a previously allocated generation in the same group. This is 
accomplished by the specification of DCB attributes for the new generation as 
described below. 


If you are using absolute generation and version numbers, DCB attributes for a 
generation can be supplied directly in the DCB parameter of the DD statement 
defining the generation to be created and cataloged. 


If you are using relative generation numbers to catalog generations, DCB 
attributes can be supplied either: (1) by creating a model DSCB on the volume 
on which the index resides (the volume containing the SYSCTLG data set) or 
(2) by referring to a cataloged data set for the use of its attributes. Attributes 
can be supplied before you catalog a generation, when you catalog it, or at both 
times, as follows: 


1. Create a model DSCB on the volume on which your index resides. You can 
provide initial DCB attributes when you create your model; however, you 
need not provide any attributes at this time. Initial or overriding attributes 
can be supplied when you create and catalog a generation.' To create a model 
DSCB, include the following DD statement in the job step that builds the 
index or in any other job step that precedes the step in which you create and 
catalog your generation. 


The DSNAME is the common name by which each generation is identified; 
XXXXXxX is the serial number of the volume containing the catalog. If no DCB 
subparameters are desired initially, you need not code the DCB parameter. 


//name DD DSNAME=datagrpname,DISP=(,KEEP),SPACE=(TRK,(0)), 
7] UNIT=yyyy, VWOLUME=SER=xxxxxx, 
lee DCB=(applicable subparameters) 


' Only one model DSCB is necessary for any number of generations. If you plan to use only one 


model, do not supply DCB attributes when you create the model. When you subsequently 
create and catalog a generation, include necessary DCB attributes in the DD statement 
referring to the generation. In this manner, any number of generation data groups can refer 
to the same model. 


~ 
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2. You do not need to create a model DSCB if you can refer to a cataloged data 
set whose attributes are identical to those you desire or to an existing model 
DSCB for which you can supply overriding attributes. A cataloged data set 
referred to in this manner must reside on the same volume as your index. To 
refer to a cataloged data set for the use of its attributes, specify 
DCB=(dsname) on the DD statement that creates and catalogs your 
generation. To refer to an existing model, specify DCB=(modeldscbname, 
your attributes) on the DD statement that creates and catalogs your 
generation. 


A generation can be cataloged through the use of normal job control language 
procedures or through the use of IEHPROGM. 


Using JCL Procedures to Catalog a Generation 


Assuming that a generation data group index has been built and that provisions 
have been made for supplying DCB attributes, a generation is created and 
cataloged in the same manner as any other type of data set. 


When you use relative numbers in job control language procedures, you must 
include the CATLG subparameter in the DD statement defining the new 
generation. When you use absolute generation and version numbers, you need 
not catalog the new generation immediately. 


Using IEHPROGM to Catalog a Generation 


The CATLG function of IEHPROGM can be used to catalog a generation. 
Again, the prerequisite for cataloging a generation is the existence of a 
generation data group index in the SYSCTLG data set. 


Note: You must always use an absolute generation and version number to catalog 
or uncatalog a generation using IEHPROGM. (IEHMOVE and IEHLIST also 
require that absolute generation and version numbers be used.) 


Creating an ISAM Data Set as Part of a Generation Data Group 


To create an indexed-sequential data set as part of a generation data group, you 
must: (1) create the indexed-sequential data set separately from the generation 
group and (2) use IEHPROGM to put the indexed-sequential data set into the 
generation group. 


Use the RENAME function to rename the data set. Then use the CATLG 
function to catalog the data set. For instance, if MASTER is the name of the 
generation data group, and GggggVvwv is the absolute generation name, you 
would code the following: 


RENAME DSNAMES=ISAM,VOL=2314=SCRTCH, NEWNAME=MASTER.GggggVvv 
CATLG DSNAME=MASTER. GggggVwv, VOL=2314=SCRTCH 


Retrieving a Generation 


A generation may be retrieved through the use of job control language 
procedures. Any operation that can be applied to a non-generation data set can 
be applied to a generation. For example, a generation can be updated and 
reentered in the catalog, or it can be copied, printed, punched, or used in the 
creation of new generation or non-generation data sets. 


You can retrieve a generation by using either relative generation numbers or 
absolute generation and version numbers. 
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Because two or more jobs can compete for the same resource, generation data 
groups should be updated with caution, as follows: 


1. No two jobs running concurrently should refer to the same generation data 
group. As a partial safeguard against this situation, use absolute generation 
and version numbers when cataloging or retrieving a generation in a 
multiprogramming environment. If you use relative numbers, a job running 
concurrently may update the generation data group index, perhaps cataloging a 
new generation which you will then retrieve in place of the one you wanted. 


2. Even when using absolute generation and version numbers, a job running 
concurrently might catalog a new version of a generation or perhaps delete the 
generation you wished to retrieve. For this reason, some degree of control 
should be maintained over the execution of job steps referring to generation 
data groups. 


Generation Data Group Examples 


Generation Example 1 
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The following examples show some of the ways in which generations can be 
created and cataloged, or retrieved and used as source data in the creation of 
new generation or non-generation data sets. 


In this example, an IEHPROGM job step, STEPA, creates a model DSCB and 
builds a generation-data-group index. STEPB, an IEBGENER job step, creates 
and catalogs a sequential generation from card input. 


The example follows: 


//BLDINDX JOB 
//STEPA EXEC PGM=IEHPROGM 
//SYSPRINT DD SYSOUT=A 
//BLDDSCB- DD DSNAME=A.B.C,DISP=( ,KEEP),SPACE=(TRK,(0)), 
// DCB=( LRECL=80,RECFM=FB, BLKSIZE=800 ), 
// VOLUME=SER=111111,UNIT=2314 
//SYSIN DD * 
BLDG INDEX=A.B.C,ENTRIES=10,EMPTY,DELETE 
/* 
f/STEPB EXEC PGM=IEBGENER 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD DUMMY 
JF OVSUTZ DD DSNAME=A.B.C(+1),UNIT=2314,DISP=( ,CATLG), 
id VOLUME=SER=231400, SPACE=( TRK, 20 ) 
J/SYSUTI DD DATA 


(input card data) 

/* 

The control statements are discussed below: 

e BLDDSCB DD creates a model DSCB on the system residence volume. 


e SYSIN DD indicates that a utility control statement (BLDG) is included next 
in the input stream. 


e BLDG specifies the generation data group name A.B.C and makes provision 
for ten entries in the group. When the index is filled, it is to be emptied, and 
all of the generations are to be deleted. 


e SYSUT2 DD defines an output sequential generation. The generation is 
assigned the absolute generation and version number GO001V00 in the index. 


e SYSUT1 DD defines the input card data set. 


Any subsequent job that causes the deletion of the generations should include 
DD statements defining the devices on which the volumes containing those 
generations are to be mounted. Each generation for which no DD statement is 
included is uncataloged at that time, but not deleted. 


After the generation data group is emptied, new generations continue to be 
assigned generation numbers according to the last generation number assigned 
before the empty operation. To restart the numbering operation (that is, to reset 
to G0000V00 or GO001V00), it is necessary to uncatalog all the old generation 
data sets and then rename and recatalog, beginning with GOOOOVOO. 


Generation Example 2 


In this example, a second generation is created and cataloged in the index built in 
Example 1. DCB attributes are included to override those attributes that were 
specified when the model DSCB was created. 


The example follows: 


Tole JOB 

ae EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD DUMMY 

//SYSUT2 DD DSNAME=A.B.C(+1),UNIT=2314,DISP=(,CATLG), 
// DCB=( LRECL=80,RECFM=FB,BLKSIZE=1600), 

// VOLUME=SER=231401,SPACE=( TRK,20) 

//SYSUT1 DD DATA 


(input data set) 

/* 

The control statements are discussed below: 

¢ SYSUT2 DD defines an output sequential generation. The generation is 
assigned the absolute generation and version number GO0002V00 in the index. 
The specified DCB attributes override those initially specified in the model 
DSCB. The DCB attributes specified when the model DSCB was created 


remain unchanged; that is, those attributes are applicable when you catalog a 
succeeding generation unless you specify overriding attributes at that time. 


e SYSUT1 DD defines the input card data set. 


Generation Example 3 


In this example, a generation data group index for generation data group A.B.C 
is built. Three existing non-cataloged, non-generation data sets are renamed; the 
renamed data sets are cataloged as generations in the generation data group 
index. 
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Generation Example 4 
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The example follows: 


72 
//BLDINDEX JOB 
// EXEC PGM=IEHPROGM 
//SYSPRINT DD  SYSOUT=A 
//DD1 DD .UNIT=2314, VOLUME=SER=111111,DISP=OLD 
//DD2 DD UNIT=(2314,,DEFER),DISP=OLD, 
// SOLUME=( PRIVATE, , SER=( 231400) ) 
//SYSIN DD * 
BLDG INDEX=A.B.C, ENTRIES=10 
RENAME DSNAME=DATASET1,VOL=2314=231400, ae 
NEWNAME=A.B.C.G0001V00 
RENAME DSNAME=DATASET2, VOL=2314=231400, are 
NEWNAME=A .B.C.GO0002V00 
RENAME DSNAME=DATASET3, VOL=2314=231400, (Sc 
NEWNAME=A .B.C.G0003V00 
CATLG § DSNAME=A.B.C.G0001V00, VOL=2314=231400 
CATLG DSNAME=A.B.C.G0002V00, VOL=2314=231400 
CATLG DSNAME=A.B.C.G0003V00, VOL=2314=231400 
/* 


The control statements are discussed below: 


¢ DD1 DD defines the system residence volume on which the SYSCTLG data 
set resides. 


¢ BLDG specifies the generation group name A.B.C and makes provision for ten 
entries in the index. The oldest generation is to be uncataloged when the index 
becomes full. No generations are to be scratched. 


e The RENAME statements rename three non-generation data sets residing on a 
2314 disk volume. 


e CATLG catalogs the renamed data sets in the generation data group index. 


Note: Because the DCB parameters were supplied when the non-generation data 
sets were created, no DCB parameters are now specified; therefore, no model 
DSCB is required. 


In this example, a non-generation version of a generation data set is to be made. 
The generation is represented as the next to the latest entry in the index. The 
name of the resultant data set is TESTSET. This example assumes that the 
generation to be copied is partitioned. 


The example follows: 


/ /COPY JOB 

i, EXEC PGM=IEBCOPY 

//SYSPRINT DD  SYSOUT=A 

//SYSUT1 DD  DSNAME=A.B.C(-1),DISP=OLD 

//SYSUT2 DD  DSNAME=TESTSET,UNIT=2314,DISP=( ,KEEP), 
// VOLUME=SER=231400,SPACE=(TRK,(20,10,5)), 

// DCB=( RECFM=FB, LRECL=80, BLKSIZE=80 ) 

//SYSIN DD DUMMY 

/* 


The control statements are discussed below: 
¢ SYSUT1 DD defines the generation from which a copy is to be made. 


e SYSUT2 DD defines a partitioned data set (TESTSET) on a 2314 output 
volume. The DCB attributes in this statement are identical to those assigned to 
the generation. (Reblocking is permitted, but the SYSUT2 block size 
specification must be a multiple of the original block size.) 


Generation Example 5 


In 


this example, a partitioned generation consisting of three members is to be 


used as source data in the creation of a new generation. IEBUPDTE is to be 
used to add a fourth member to the three source members and to number the 
new member. The resultant data set is to be cataloged as a new generation. 


The example follows: 


Lo 
// 
pf, 
jah 
// 
jaf 
es 
ee 
./ 
af 
a 
ae 
-/ 


JOB 
EXEC PGM=IEBUPDTE, PARM=MOD 
SYSPRINT DD SYSOUT=A 
SYSUT1 DD  DSNAME=A.B.C(0),DISP=OLD 
SYSUT2 DD DSNAME=A.B.C(+1),DISP=( ,CATLG),UNIT=2314, 
VOLUME=SER=231400, SPACE=( TRK,(100,10,10)), 
DCB=( RECFM=FB, LRECL=80 , BLKSIZE=800 ) 


3 Lo LN DD DATA 
REPRO NAME=MEM1 , LEVEL=00, SOURCE=0, LIST=ALL 
REPRO NAME=MEM2, LEVEL=00, SOURCE=0, LIST=ALL 
REPRO NAME=MEM3, LEVEL=00, SOURCE=0, LIST=ALL 
ADD NAME=MEM4, LEVEL=00 , SOURCE=0, LIST=ALL, IGNORE=EOF 
NUMBER NEW1=10, INCR=5 


(data cards comprising MEM4) 


-/ 
/* 


ENDUP 


The control statements are discussed below: 


SYSUT1 DD defines the latest generation, which is used as source data. 


SYSUT2 DD defines the new generation, which is created from the source 
generation and from an additional member included as input card data. 


The REPRO function statements reproduce the named source members in the 
output generation. 


The ADD function statement specifies that the data cards following the input 
stream be included as MEM4. 


The NUMBER detail statement indicates that the new member is to have 
sequence numbers assigned in columns 73 through 80. The first record is 
assigned sequence number 10. The sequence number of each successive record 
is incremented by 5. 


ENDUP signals the end of input card data. 


Note: This example assumes that a model DSCB exists on the catalog volume on 
which the index was built. 
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Appendix E: Processing User Labels 


User labels can be processed by IEBGENER, IEBCOMPR, IEBPTPCH, 
IEHMOVE, IEBCTRIN, and IEBUPDTE. In some cases, user label processing is 
automatically performed; in other cases, you must indicate the processing to be 
performed. In general, user label support allows the utility program user to: 


e Process user labels as data set descriptors. 
e Process user labels as data. 


e Total the processed records prior to each WRITE command (IEBGENER and 
IEBUPDTE only). 


For either of the first two options, the user must specify standard labels (SUL) 
on the DD statement that defines each data set for which user label processing is 
desired. For totaling routines, OPTCD=T must be specified on the DD 
statement. 


The user cannot update labels by means of the IEBUPDTE program. This 
function must be performed by a user’s label processing routines. IEBUPDTE 
will, however, allow you to create labels on the output data set from data 
supplied in the input stream. See the discussion of the LABEL statement in the 
chapter “JEBUPDTE Program.” 


IEHMOVE does not allow exits to user routines and does not recognize options 
concerning the processing of user labels as data. IEHMOVE always moves or 
copies user labels directly to a new data set. See the chapter ‘“IEHMOVE 
Program.”’ 


Volume switch labels of a multivolume data set cannot be processed by IEHMOVE, 
IEBGENER, or IEBUPDTE. Volume switch labels are therefore lost when these 
utilities create output data sets. To ensure that volume switch labels are retained, 
process multivolume data sets one volume at a time. 


Processing User Labels as Data Set Descriptors 


When user labels are to be processed as data set descriptors, one of the user’s 
label processing routines receives control for each user label of the specified type. 
The user’s routine can include, exclude, or modify the user label. Processing of 
user labels as data set descriptors is indicated on an EXITS statement with 
keyword parameters that name the label processing routine to be used. 


The EXIT keyword parameters indicate that a user routine should receive control 
each time the OPEN, EOV, or CLOSE routine encounters a user label of the 
type specified. 


Figure 71 illustrates the action of the system at OPEN, EOV, or CLOSE time. 
When OPEN, EOV, or CLOSE recognizes a user label and when SUL has been 
specified on the DD statement for the data set, control is passed to the utility 
program. Then, if an exit has been specified for this type, of label, the utility 
program passes control to the user routine. The user’s routine processes the label 
and returns control, along with a return code, to the utility program. The utility 
program then returns control to OPEN, EOV, or CLOSE. 
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OPEN/EOV/CLOSE 
User’s label 
processing routine 


Figure 71. System Action at OPEN, EOV, or CLOSE Time 


This cycle is repeated up to eight times, depending upon the number of user 
labels in the group and the return codes supplied by the user’s routine. 


Exiting to a User’s Totaling Routine 


When an exit is taken to a user’s totaling routine, an output record is passed to 
the user’s routine just before the record is written. The first halfword of the 


totaling area pointed to by the parameter contains the length of the totaling area, 


and should not be used by the user’s routine. If the user has specified user label 
exits, this totaling area (or an image of this area) is pointed to by the parameter 
list passed to the appropriate user label routine. 


Note: An output record is defined as a physical record (block), except when 
IEBGENER is used to process and reformat a data set that contains spanned 
records. 


Processing User Labels as Data 
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When user labels are processed as data, the group of user labels, as well as the 
data set, is subject to the normal processing done by the utility program. The 
user can have his labels printed or punched by JIEBPTPCH, compared by 
IEBCOMPR, or copied by IEBGENER. 


To specify that user labels are to be processed as data, include a LABELS 
statement in the job step that is to process user labels as data. 


There is no direct relationship between the LABELS statement and the EXITS 
statement. Either or both can appear in the control statement stream for an 
execution of a utility program. If there are user label-processing routines, 
however, their return codes may influence the processing of the labels as data. In 
addition, a user’s output label-processing routine can override the action of a 
LABELS statement because it receives control before each output label is 
written. At this time the label created by the utility as a result of the LABEL 
statement is in the label buffer, and the user’s routine can modify it. 


The code returned by the user’s totaling routine determines system response as 
follows: 


e QO, which specifies that processing is to continue, but no further exits are to be 
taken. 


e 4, which specifies that normal processing is to continue. 


e 8, which specifies that processing is to terminate, except for EOD processing 
on the output data set (user label processing). 


e 16, which specifies that processing is to be terminated. 
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libraries, updating ‘Svenbolic Bo hg a> Ge the Ver eae eae ten ewe 199 
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a sequential dataset 4: -2:.:4 2. Gee 2 soa tos EAR BS 161 
a volume table of contents ......... 6s BOP 
data-set passwords... .......... 0.0484 325 
error Statistics by volume (ESV) records . ...... 259 
system control data ................ 267 
EISTCTELG Statements Satie Be on th, Hh Ry ce ch ce 8 273 
LISTPDS -Statement- <a.0 fos te e. Oe ae eked a a ee fs 213 
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picture, user-specified... .............4 102 
prerequisite publications ...............8. fi 
print specifications 
Standard... % 42 a A BOI ee eS ho Re AS 161 
USER 65> i+, 0% hee, vas Gene as Of oe 8s 2. ee. Gl vate a ee 161 
PRINT Statements: <- 4-0, 40 l6- woe Se EH a ee er SS 164 
printing 
a partitioned directory .........2.. 162,163,267 
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fOr TE BP TPG. . ae a x ve go Be Gi ec ahe cad We Me se % 170 
record groups, assigning. . ............4.. 131 
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